chore: import upstream snapshot with attribution

apps/sim/lib/api/contracts/workspace-fork.ts

@@ -0,0 +1,774 @@
+import { z } from 'zod'
+import { nonEmptyIdSchema, workspaceIdSchema } from '@/lib/api/contracts/primitives'
+import { defineRouteContract } from '@/lib/api/contracts/types'
+import { workspaceSchema } from '@/lib/api/contracts/workspaces'
+
+const workspaceIdParamsSchema = z.object({ id: nonEmptyIdSchema })
+
+export const forkRemapKindSchema = z.enum([
+  'credential',
+  'env-var',
+  'knowledge-base',
+  'knowledge-document',
+  'table',
+  'file',
+  'mcp-server',
+  'custom-tool',
+  'skill',
+])
+
+export const forkResourceTypeSchema = z.enum([
+  'workflow',
+  'oauth_credential',
+  'service_account_credential',
+  'env_var',
+  'table',
+  'knowledge_base',
+  'knowledge_document',
+  'file',
+  'mcp_server',
+  /**
+   * Workflow-publishing MCP server identity (parent shell <-> fork copy), seeded at fork so a
+   * sync can mirror `workflow_mcp_tool` attachments onto the mapped counterpart. System-managed;
+   * never user-mapped (nothing in a workflow references these servers).
+   */
+  'workflow_mcp_server',
+  'custom_tool',
+  'skill',
+])
+
+/**
+ * Resource types a user may map via the mapping editor. Excludes `workflow` (identity is
+ * system-managed - seeded at fork, maintained by promote, dissolved by rollback - and must never
+ * be written through the editor, or a crafted entry could repoint a promote at the wrong target
+ * workflow), `workflow_mcp_server` (identity is likewise system-managed - seeded when a fork
+ * copies the server shells - and nothing in a workflow references one, so there is never a
+ * mapping entry to edit), AND `knowledge_document` (a document is never a standalone mapping: it
+ * follows its parent knowledge base, re-picked in that KB's reconfigure flow and auto-remapped
+ * when the KB is copied - the mapping view never emits one and `listForkResourceCandidates`
+ * returns none).
+ */
+export const forkMappableResourceTypeSchema = forkResourceTypeSchema.exclude([
+  'workflow',
+  'workflow_mcp_server',
+  'knowledge_document',
+])
+export type ForkMappableResourceType = z.infer<typeof forkMappableResourceTypeSchema>
+
+export const forkDirectionSchema = z.enum(['push', 'pull'])
+
+/**
+ * The remappable, copyable resource kinds a sync can copy into the target when they are
+ * unmapped (the fork-style copy at promote time), whether referenced by the synced workflows or
+ * not. Excludes credentials and env vars (never copied); documents are auto-copied with their
+ * parent knowledge base, not selected individually. Workspace `file` references are keyed by
+ * storage key (not `workspace_files.id`) and copied like fork does.
+ */
+export const forkCopyableKindSchema = z.enum([
+  'knowledge-base',
+  'table',
+  'custom-tool',
+  'skill',
+  'file',
+  /**
+   * External MCP servers copy as CONFIG rows (transport/url/headers verbatim; OAuth tokens
+   * never copied - oauth-auth servers land disconnected until re-authorized in the target).
+   */
+  'mcp-server',
+])
+export type ForkCopyableKind = z.infer<typeof forkCopyableKindSchema>
+
+export const forkLineageNodeSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  organizationId: z.string().nullable(),
+  /**
+   * Whether the viewer has any access (read or higher, explicit or org-derived) to this
+   * lineage workspace. Drives the Forks page's row-action gating - lineage rows are visible
+   * to any admin of the CURRENT workspace, who may hold no access to the other side.
+   */
+  viewerAccessible: z.boolean(),
+})
+
+/** A live fork of this workspace, listed read-only on the Forks settings page. */
+export const forkLineageChildSchema = forkLineageNodeSchema.extend({
+  /** When the fork was created (ISO timestamp). */
+  createdAt: z.string(),
+})
+
+export const getForkLineageContract = defineRouteContract({
+  method: 'GET',
+  path: '/api/workspaces/[id]/fork/lineage',
+  params: workspaceIdParamsSchema,
+  response: {
+    mode: 'json',
+    schema: z.object({
+      workspaceId: z.string(),
+      parent: forkLineageNodeSchema.nullable(),
+      /** Live forks created from this workspace, newest first. */
+      children: z.array(forkLineageChildSchema),
+      /** The most recent undoable promote into this workspace, for the rollback UI. */
+      undoableRun: z
+        .object({
+          otherWorkspaceId: z.string(),
+          otherName: z.string(),
+          direction: forkDirectionSchema,
+        })
+        .nullable(),
+    }),
+  },
+})
+export type ForkLineageNodeApi = z.output<typeof forkLineageNodeSchema>
+export type ForkLineageChildApi = z.output<typeof forkLineageChildSchema>
+export type GetForkLineageResponse = z.output<typeof getForkLineageContract.response.schema>
+
+const forkResourceIdList = z.array(nonEmptyIdSchema).max(2000).optional()
+
+export const forkResourceSelectionSchema = z.object({
+  files: forkResourceIdList,
+  tables: forkResourceIdList,
+  knowledgeBases: forkResourceIdList,
+  customTools: forkResourceIdList,
+  skills: forkResourceIdList,
+  /**
+   * External MCP servers, copied as config rows (transport/url/headers) so MCP tool selections
+   * in the forked workflows keep working. OAuth tokens are never copied - an oauth-auth server
+   * lands disconnected in the child until re-authorized; tools re-discover on first use.
+   */
+  mcpServers: forkResourceIdList,
+  /** Workflow-publishing MCP servers, copied as config-only shells with no workflows attached. */
+  workflowMcpServers: forkResourceIdList,
+})
+
+export const forkWorkspaceBodySchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100, 'Name is too long').optional(),
+  copy: forkResourceSelectionSchema.optional(),
+})
+export const forkWorkspaceContract = defineRouteContract({
+  method: 'POST',
+  path: '/api/workspaces/[id]/fork',
+  params: workspaceIdParamsSchema,
+  body: forkWorkspaceBodySchema,
+  response: {
+    mode: 'json',
+    schema: z.object({
+      // Full workspace row so the client can merge it into the workspace-list cache
+      // (parity with create), not just the lineage node.
+      workspace: workspaceSchema,
+      workflowsCopied: z.number().int(),
+    }),
+  },
+})
+export type ForkWorkspaceBody = z.input<typeof forkWorkspaceBodySchema>
+export type ForkWorkspaceResponse = z.output<typeof forkWorkspaceContract.response.schema>
+
+export const forkCopyableResourceSchema = z.object({ id: z.string(), label: z.string() })
+export type ForkCopyableResource = z.output<typeof forkCopyableResourceSchema>
+
+/**
+ * A copyable workspace file plus its folder grouping. `folderId`/`folderName` are null when
+ * the file sits at the workspace root (or its folder was deleted). Files are the only copyable
+ * kind that nests in the picker (folder ▸ file); every other kind stays flat at the top level.
+ */
+export const forkCopyableFileSchema = forkCopyableResourceSchema.extend({
+  folderId: z.string().nullable(),
+  folderName: z.string().nullable(),
+})
+export type ForkCopyableFile = z.output<typeof forkCopyableFileSchema>
+
+export const getForkResourcesContract = defineRouteContract({
+  method: 'GET',
+  path: '/api/workspaces/[id]/fork/resources',
+  params: workspaceIdParamsSchema,
+  response: {
+    mode: 'json',
+    schema: z.object({
+      files: z.array(forkCopyableFileSchema),
+      tables: z.array(forkCopyableResourceSchema),
+      knowledgeBases: z.array(forkCopyableResourceSchema),
+      customTools: z.array(forkCopyableResourceSchema),
+      skills: z.array(forkCopyableResourceSchema),
+      /** External MCP servers (config rows; OAuth tokens never copied). */
+      mcpServers: z.array(forkCopyableResourceSchema),
+      workflowMcpServers: z.array(forkCopyableResourceSchema),
+      deployedWorkflowCount: z.number().int(),
+    }),
+  },
+})
+export type GetForkResourcesResponse = z.output<typeof getForkResourcesContract.response.schema>
+
+export const forkMappingCandidateSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  providerId: z.string().optional(),
+})
+
+export const forkMappingEntrySchema = z.object({
+  kind: forkRemapKindSchema,
+  resourceType: forkMappableResourceTypeSchema,
+  sourceId: z.string(),
+  sourceLabel: z.string(),
+  targetId: z.string().nullable(),
+  /** True when `targetId` is an unconfirmed auto-suggestion (no persisted mapping yet). */
+  suggested: z.boolean(),
+  required: z.boolean(),
+  candidates: z.array(forkMappingCandidateSchema),
+  /**
+   * True when the target workspace has more candidates of this kind than the picker
+   * loads, so the list shown is partial. The UI surfaces a "refine to find more"
+   * notice; the chosen target is validated by exact id on save (never capped).
+   */
+  candidatesTruncated: z.boolean(),
+})
+export type ForkMappingEntry = z.output<typeof forkMappingEntrySchema>
+
+export const getForkMappingQuerySchema = z.object({
+  otherWorkspaceId: workspaceIdSchema,
+  direction: forkDirectionSchema.default('push'),
+})
+export const getForkMappingContract = defineRouteContract({
+  method: 'GET',
+  path: '/api/workspaces/[id]/fork/mapping',
+  params: workspaceIdParamsSchema,
+  query: getForkMappingQuerySchema,
+  response: {
+    mode: 'json',
+    schema: z.object({
+      childWorkspaceId: z.string(),
+      parentWorkspaceId: z.string(),
+      sourceWorkspaceId: z.string(),
+      targetWorkspaceId: z.string(),
+      entries: z.array(forkMappingEntrySchema),
+    }),
+  },
+})
+export type GetForkMappingResponse = z.output<typeof getForkMappingContract.response.schema>
+
+/**
+ * One dependent field's value in the stored mapping. The sync modal and the Forks
+ * settings page's mapping editor send the full set for every dependent whose parent is
+ * mapped; the server persists them to `workspace_fork_dependent_value` (promote also
+ * applies them verbatim to the target blocks), so the user's selection survives every
+ * future sync without re-picking. `blockId` is the deterministic fork block id, so the
+ * value lands on the right block.
+ */
+export const forkDependentValueEntrySchema = z.object({
+  workflowId: nonEmptyIdSchema,
+  blockId: nonEmptyIdSchema,
+  subBlockKey: z.string().min(1, 'subBlockKey is required'),
+  value: z.string(),
+})
+export type ForkDependentValueEntry = z.input<typeof forkDependentValueEntrySchema>
+
+export const updateForkMappingBodySchema = z.object({
+  otherWorkspaceId: workspaceIdSchema,
+  direction: forkDirectionSchema,
+  entries: z
+    .array(
+      z.object({
+        resourceType: forkMappableResourceTypeSchema,
+        sourceId: z.string().min(1),
+        targetId: z.string().min(1).nullable(),
+      })
+    )
+    .max(5000),
+  /**
+   * The full stored mapping of dependent-field values for the workflows it names; persisted
+   * to `workspace_fork_dependent_value` alongside the mapping entries (each named workflow's
+   * stored set is replaced by exactly what was sent - cleared fields drop out). Omitting the
+   * field leaves the stored mapping untouched. Unlike promote this only stores the values;
+   * they are applied to the target blocks on the next sync.
+   */
+  dependentValues: z.array(forkDependentValueEntrySchema).max(2000).optional(),
+})
+export const updateForkMappingContract = defineRouteContract({
+  method: 'PUT',
+  path: '/api/workspaces/[id]/fork/mapping',
+  params: workspaceIdParamsSchema,
+  body: updateForkMappingBodySchema,
+  response: {
+    mode: 'json',
+    schema: z.object({ success: z.literal(true), updated: z.number().int() }),
+  },
+})
+export type UpdateForkMappingBody = z.input<typeof updateForkMappingBodySchema>
+
+export const forkUnmappedReferenceSchema = z.object({
+  kind: forkRemapKindSchema,
+  sourceId: z.string(),
+  required: z.boolean(),
+  blockName: z.string().optional(),
+})
+
+export const forkWorkflowChangeSchema = z.object({
+  action: z.enum(['update', 'create', 'archive']),
+  /** Workflow name in the workspace the modal is open in. */
+  currentName: z.string(),
+  /** Workflow name in the sync-partner workspace (differs from `currentName` after a rename). */
+  otherName: z.string(),
+})
+
+/**
+ * A configured selector field (Gmail label, Slack channel, KB document, ...) that
+ * `dependsOn` a remappable parent resource - a credential or a knowledge base - so a
+ * sync clears it whenever that parent's target changes. The modal renders a controlled
+ * selector against the newly-chosen parent (using `selectorKey` + `context` + the new
+ * parent value under `parentContextKey`) so the user re-picks the value in place,
+ * pre-sync, instead of having it cleared and reconfigured after. `targetBlockId` is the
+ * deterministic fork block id, matching the engine, so the re-pick lands on the right
+ * block. Only fields the source actually had set are emitted (the active operation's),
+ * so blocks aren't padded with every operation variant.
+ */
+export const forkDependentReconfigSchema = z.object({
+  /** The remappable parent resource kind whose target swap clears this field. */
+  parentKind: z.enum(['credential', 'knowledge-base', 'table']),
+  /** Source id of that parent (matches a mapping entry's `sourceId`). */
+  parentSourceId: z.string(),
+  /** SelectorContext key the new parent value is supplied under (`oauthCredential` | `knowledgeBaseId` | `tableId`). */
+  parentContextKey: z.string(),
+  targetWorkflowId: z.string(),
+  targetBlockId: z.string(),
+  blockName: z.string(),
+  subBlockKey: z.string(),
+  selectorKey: z.string(),
+  /** Plain field title (e.g. `Label`), never a `Tool: Field` composite. */
+  title: z.string(),
+  /**
+   * Display name of the nested `tool-input` tool this field belongs to (e.g. `Gmail` /
+   * `Gmail 1`). Absent for top-level block subblocks.
+   */
+  toolName: z.string().optional(),
+  /**
+   * The field's stored value (from the persisted mapping), so the always-on reconfigure listing
+   * pre-fills the selector with what the user last set. Empty string when unset; for an edge
+   * that predates the store the TARGET's currently-configured value is the fallback (never the
+   * source's, which would overwrite the target's own selection on the first sync). After a
+   * parent target CHANGE the modal ignores this and starts blank, since the old value no longer
+   * resolves against the new parent.
+   */
+  currentValue: z.string(),
+  /**
+   * The field's raw value in the SOURCE workflow state (what the source references today),
+   * untouched by the stored/target-draft overlay that `currentValue` carries. Seeds the selector
+   * when the parent is resolved by COPY: the copy brings the source parent's children along, so
+   * the source reference is exactly what the copied parent will contain.
+   */
+  sourceValue: z.string(),
+  /** Whether the field is required - a required empty field blocks Sync. */
+  required: z.boolean(),
+  /**
+   * SelectorContext key this field's own value supplies to its in-block descendants
+   * (e.g. a spreadsheet feeds `spreadsheetId` to the sheet selector). Lets the modal
+   * chain re-picks: a re-picked parent updates its children's selector context.
+   */
+  providesContextKey: z.string().optional(),
+  /**
+   * SelectorContext keys this field needs from in-block siblings (excluding the parent
+   * the modal already supplies). The modal keeps the field disabled until each sibling
+   * that provides one of these keys has been re-picked, so a child never queries a stale
+   * upstream value.
+   */
+  consumesContextKeys: z.array(z.string()),
+  /** Source-derived selector context (sans the parent key the modal supplies). */
+  context: z.record(z.string(), z.string()),
+})
+export type ForkDependentReconfig = z.output<typeof forkDependentReconfigSchema>
+
+/**
+ * Every workflow a mapped resource (any kind) is used in, for the always-on reconfigure
+ * listing under each mapping entry. Joined to the entry by `(parentKind, parentSourceId)`;
+ * the modal cross-references {@link forkDependentReconfigSchema} per workflow to decide which
+ * rows are expandable (have configurable dependents) vs. greyed (used here, nothing to tune).
+ */
+export const forkResourceUsageSchema = z.object({
+  parentKind: forkRemapKindSchema,
+  parentSourceId: z.string(),
+  workflows: z.array(
+    z.object({
+      /** Deterministic fork (target) workflow id - matches a dependent's `targetWorkflowId`. */
+      workflowId: z.string(),
+      workflowName: z.string(),
+    })
+  ),
+})
+export type ForkResourceUsage = z.output<typeof forkResourceUsageSchema>
+
+/** Fields shared by every cleared-ref variant: the labels to phrase the "will be cleared" line. */
+const forkClearedRefBaseSchema = z.object({
+  targetWorkflowId: z.string(),
+  workflowName: z.string(),
+  blockId: z.string(),
+  blockLabel: z.string(),
+  fieldLabel: z.string(),
+  sourceId: z.string(),
+  sourceLabel: z.string(),
+})
+
+/**
+ * A reference in a synced source workflow that this sync would blank in the target, with the
+ * labels to phrase it as "{blockLabel} will lose {fieldLabel} in workflow {workflowName}". A
+ * discriminated union on `cause` so clients narrow exhaustively (only `dependent` carries the parent
+ * fields):
+ *  - `reference`: an unmapped remappable resource (`kind`). BLOCKS the sync until the user maps it
+ *    OR selects it for copy (matched to a mapping entry by `${kind}:${sourceId}`); the entry drops
+ *    off the blocker list once resolved.
+ *  - `workflow`: a `workflow-selector`/`workflow_input` ref to a workflow not carried into the
+ *    target. BLOCKS the sync; resolved outside the modal (deploy the referenced workflow in the
+ *    source, or remove/fix the reference).
+ *  - `dependent`: a create-target dependent selector a remapped parent clears. NOT a blocker (the
+ *    reconfigure flow owns dependents). Carries the parent (`parentKind`/`parentSourceId`); when the
+ *    child follows its parent (a document under a knowledge base) the client drops it once that
+ *    parent is mapped/copied, else it stays (credential label / table column).
+ */
+export const forkClearedRefSchema = z.discriminatedUnion('cause', [
+  forkClearedRefBaseSchema.extend({
+    cause: z.literal('reference'),
+    /** The unmapped remappable resource (never `workflow`). */
+    kind: forkRemapKindSchema,
+    /**
+     * True when the referenced resource no longer exists (deleted/archived) in the SOURCE
+     * workspace, so it cannot be offered for copy - the resolution is mapping the dead source id
+     * to a live target resource, or fixing the source workflow. Collected as `false` and
+     * annotated post-collection by the source-liveness check (`annotateForkClearedRefSourceLiveness`).
+     */
+    sourceDeleted: z.boolean(),
+  }),
+  forkClearedRefBaseSchema.extend({
+    cause: z.literal('workflow'),
+    kind: z.literal('workflow'),
+  }),
+  forkClearedRefBaseSchema.extend({
+    cause: z.literal('dependent'),
+    /** Mirrors `parentKind` - the parent resource the cleared dependent hangs off. */
+    kind: forkRemapKindSchema,
+    /** The dependsOn parent; the entry drops off once this parent is mapped/copied (KB-document case). */
+    parentKind: forkRemapKindSchema,
+    parentSourceId: z.string(),
+  }),
+])
+export type ForkClearedRef = z.output<typeof forkClearedRefSchema>
+
+/**
+ * Why a would-clear reference blocks the sync, so clients can phrase the resolution:
+ *  - `unmapped-copyable`: a live copyable-kind resource (table / KB / file / custom tool /
+ *    skill / external MCP server) with no target mapping - resolve by mapping it or selecting
+ *    it for copy.
+ *  - `source-deleted`: the referenced resource was deleted in the source - resolve by mapping the
+ *    dead id to an existing live target resource, or by fixing/archiving the source workflow.
+ *  - `workflow-missing`: a cross-workflow reference to a workflow not carried into the target -
+ *    resolve by deploying the referenced workflow in the source, or removing the reference.
+ */
+export const forkSyncBlockerReasonSchema = z.enum([
+  'unmapped-copyable',
+  'source-deleted',
+  'workflow-missing',
+])
+export type ForkSyncBlockerReason = z.output<typeof forkSyncBlockerReasonSchema>
+
+/**
+ * One reference that blocked a promote at the server gate (the authoritative in-tx re-check of
+ * the would-clear set). Mirrors the cleared-ref labels so the client can phrase each blocker;
+ * `kind` is `workflow` for cross-workflow references. `sourceLabel` may fall back to `sourceId`
+ * (the gate skips display-label loading); the modal's refreshed diff carries the labeled list.
+ */
+export const forkSyncBlockerSchema = z.object({
+  workflowName: z.string(),
+  blockLabel: z.string(),
+  fieldLabel: z.string(),
+  kind: z.union([forkRemapKindSchema, z.literal('workflow')]),
+  sourceId: z.string(),
+  sourceLabel: z.string(),
+  reason: forkSyncBlockerReasonSchema,
+})
+export type ForkSyncBlocker = z.output<typeof forkSyncBlockerSchema>
+
+export const getForkDiffQuerySchema = z.object({
+  otherWorkspaceId: workspaceIdSchema,
+  direction: forkDirectionSchema,
+})
+export const getForkDiffContract = defineRouteContract({
+  method: 'GET',
+  path: '/api/workspaces/[id]/fork/diff',
+  params: workspaceIdParamsSchema,
+  query: getForkDiffQuerySchema,
+  response: {
+    mode: 'json',
+    schema: z.object({
+      sourceWorkspaceId: z.string(),
+      targetWorkspaceId: z.string(),
+      willUpdate: z.number().int(),
+      willCreate: z.number().int(),
+      willArchive: z.number().int(),
+      /** Per-workflow change list for the sync preview. */
+      workflows: z.array(forkWorkflowChangeSchema),
+      unmappedRequired: z.array(forkUnmappedReferenceSchema),
+      unmappedOptional: z.array(forkUnmappedReferenceSchema),
+      /** Source MCP server ids that use OAuth and need re-authorization in the target. */
+      mcpReauthServerIds: z.array(z.string()),
+      /** Review-only descriptions of inline secrets that cannot be id-mapped. */
+      inlineSecretSources: z.array(z.string()),
+      /** Configured selector fields per parent (credential/KB), for the pre-sync reconfigure. */
+      dependentReconfigs: z.array(forkDependentReconfigSchema),
+      /** Every workflow each mapped resource is used in, for the always-on reconfigure listing. */
+      resourceUsages: z.array(forkResourceUsageSchema),
+      /**
+       * Copyable resources with no target mapping that the sync can copy into the target
+       * (fork-style). `referenced: true` entries are referenced by the synced workflows and
+       * default-selected in the modal (deselecting one clears its references); `referenced: false`
+       * entries exist in the source but are used by no synced workflow and default-unselected
+       * (skipping one breaks nothing). Documents under a selected knowledge base are copied
+       * automatically. `parentId`/`parentLabel` carry the folder grouping for file entries
+       * (id + name); they are null for non-file kinds and for files at the workspace root.
+       */
+      copyableUnmapped: z.array(
+        z.object({
+          kind: forkCopyableKindSchema,
+          sourceId: z.string(),
+          label: z.string(),
+          parentId: z.string().nullable(),
+          parentLabel: z.string().nullable(),
+          /** Whether any synced workflow references this resource (drives the copy default). */
+          referenced: z.boolean(),
+        })
+      ),
+      /**
+       * References this sync will blank in the target, with labels for a pre-sync "what will be
+       * cleared" list. The client filters this against the current mapping/copy selection so a
+       * `reference` item disappears once mapped or selected for copy; `workflow`/`dependent` items
+       * always clear (informational).
+       */
+      clearedRefs: z.array(forkClearedRefSchema),
+    }),
+  },
+})
+export type GetForkDiffResponse = z.output<typeof getForkDiffContract.response.schema>
+export type ForkWorkflowChange = z.output<typeof forkWorkflowChangeSchema>
+export type ForkCopyableUnmapped = GetForkDiffResponse['copyableUnmapped'][number]
+
+/**
+ * A workflow whose required dependent fields a sync cleared because their parent
+ * (e.g. a credential) was changed - the target must re-pick them. The workflow's
+ * draft holds the synced state but it was NOT redeployed (the prior version keeps
+ * running), so nothing runs broken until the user reconfigures.
+ */
+export const forkNeedsConfigurationSchema = z.object({
+  workflowName: z.string(),
+  /** Names of the blocks in the workflow that need a re-check (deduplicated). */
+  blocks: z.array(z.string()).min(1),
+})
+export type ForkNeedsConfiguration = z.output<typeof forkNeedsConfigurationSchema>
+
+/**
+ * Source resource ids (by kind) the user chose to copy into the target before the sync gate -
+ * unmapped resources, whether referenced by the synced workflows or not. Each kind's documents
+ * under a copied knowledge base are discovered + copied automatically (the user selects only
+ * the parent resources).
+ */
+export const promoteCopyResourcesSchema = z.object({
+  knowledgeBases: forkResourceIdList,
+  tables: forkResourceIdList,
+  customTools: forkResourceIdList,
+  skills: forkResourceIdList,
+  /** Workspace files to copy, identified by storage key (not `workspace_files.id`). */
+  files: forkResourceIdList,
+  /** External MCP servers to copy as config rows (OAuth tokens never copied - re-auth). */
+  mcpServers: forkResourceIdList,
+})
+export type PromoteCopyResources = z.input<typeof promoteCopyResourcesSchema>
+
+export const promoteForkBodySchema = z.object({
+  otherWorkspaceId: workspaceIdSchema,
+  direction: forkDirectionSchema,
+  /**
+   * The full stored mapping of dependent-field values; persisted to
+   * `workspace_fork_dependent_value` and applied to the target blocks verbatim. Omitting the
+   * field leaves the stored mapping untouched (the store stays the source of truth); sending
+   * an explicit `[]` clears it for the written replace targets.
+   */
+  dependentValues: z.array(forkDependentValueEntrySchema).max(2000).optional(),
+  /** Referenced-but-unmapped resources to copy into the target before the sync gate (U17). */
+  copyResources: promoteCopyResourcesSchema.optional(),
+})
+export const promoteForkContract = defineRouteContract({
+  method: 'POST',
+  path: '/api/workspaces/[id]/fork/promote',
+  params: workspaceIdParamsSchema,
+  body: promoteForkBodySchema,
+  response: {
+    mode: 'json',
+    schema: z.object({
+      promoteRunId: z.string(),
+      updated: z.number().int(),
+      created: z.number().int(),
+      archived: z.number().int(),
+      redeployed: z.number().int(),
+      deployFailed: z.number().int(),
+      unmappedRequired: z.array(forkUnmappedReferenceSchema),
+      /**
+       * References the sync would have cleared, so it was blocked without writing (the
+       * authoritative in-tx gate; non-empty only when `promoteRunId` is empty). Normally the
+       * client blocks first - this fires only when the state changed between preview and Sync.
+       */
+      blockers: z.array(forkSyncBlockerSchema),
+      /** Workflows whose required dependent fields the target must re-pick post-sync. */
+      needsConfiguration: z.array(forkNeedsConfigurationSchema),
+      /** Workflows whose optional dependent fields a swap cleared (surfaced, not gated). */
+      clearedOptional: z.array(forkNeedsConfigurationSchema),
+    }),
+  },
+})
+export type PromoteForkBody = z.input<typeof promoteForkBodySchema>
+export type PromoteForkResponse = z.output<typeof promoteForkContract.response.schema>
+
+/** Structured detail for a background job, surfaced in the Activity tab's expand row. */
+export const backgroundWorkMetadataSchema = z
+  .object({
+    /** Display name of the user who performed the action (denormalized at write time). */
+    actorName: z.string().optional(),
+    // Fork content copy
+    childWorkspaceId: z.string().optional(),
+    childWorkspaceName: z.string().optional(),
+    workflowsCopied: z.number().int().optional(),
+    tables: z.number().int().optional(),
+    knowledgeBases: z.number().int().optional(),
+    files: z.number().int().optional(),
+    copied: z.number().int().optional(),
+    failed: z.number().int().optional(),
+    /** Count of failed resources whose dangling references were cleared post-fork (U8). */
+    clearedReferences: z.number().int().optional(),
+    /** True when a reference-clear phase threw, so cleanup is incomplete (placeholders not dropped). */
+    clearingFailed: z.boolean().optional(),
+    /** Names of the resources a fork copied, by kind, for the report breakdown. */
+    workflowNames: z.array(z.string()).optional(),
+    tableNames: z.array(z.string()).optional(),
+    knowledgeBaseNames: z.array(z.string()).optional(),
+    fileNames: z.array(z.string()).optional(),
+    customToolNames: z.array(z.string()).optional(),
+    skillNames: z.array(z.string()).optional(),
+    mcpServerNames: z.array(z.string()).optional(),
+    workflowMcpServerNames: z.array(z.string()).optional(),
+    // Sync / rollback
+    /**
+     * The other side of the fork edge (by id) for sync/rollback/sync-copy rows. Written so
+     * the activity query can surface a row to BOTH edge workspaces, and so the client can
+     * tell which side a row was recorded on.
+     */
+    otherWorkspaceId: z.string().optional(),
+    otherWorkspaceName: z.string().optional(),
+    direction: z.enum(['push', 'pull']).optional(),
+    updated: z.number().int().optional(),
+    created: z.number().int().optional(),
+    archived: z.number().int().optional(),
+    redeployed: z.number().int().optional(),
+    deployFailed: z.number().int().optional(),
+    restored: z.number().int().optional(),
+    unarchived: z.number().int().optional(),
+    removed: z.number().int().optional(),
+    skipped: z.number().int().optional(),
+    /** Names of the workflows a sync changed, by action, for the report breakdown. */
+    updatedNames: z.array(z.string()).optional(),
+    createdNames: z.array(z.string()).optional(),
+    archivedNames: z.array(z.string()).optional(),
+    /** Workflows whose required dependent fields a sync left for the target to re-pick. */
+    needsConfiguration: z.array(forkNeedsConfigurationSchema).optional(),
+    /** Workflows whose optional dependent fields a sync cleared (FYI, non-blocking). */
+    clearedOptional: z.array(forkNeedsConfigurationSchema).optional(),
+  })
+  .nullable()
+export const backgroundWorkItemSchema = z.object({
+  id: z.string(),
+  workspaceId: z.string(),
+  workflowId: z.string().nullable(),
+  kind: z.enum(['deployment_side_effects', 'fork_content_copy', 'fork_sync', 'fork_rollback']),
+  status: z.enum(['pending', 'processing', 'completed', 'completed_with_warnings', 'failed']),
+  message: z.string().nullable(),
+  error: z.string().nullable(),
+  metadata: backgroundWorkMetadataSchema,
+  startedAt: z.string(),
+  completedAt: z.string().nullable(),
+})
+export type BackgroundWorkMetadata = z.output<typeof backgroundWorkMetadataSchema>
+/** Keyset pagination inputs, mirroring the audit log's (`auditLogsQuerySchema`). */
+export const getWorkspaceBackgroundWorkQuerySchema = z.object({
+  /** Opaque cursor from a prior page's `nextCursor`; omit for the first page. */
+  cursor: z.string().optional(),
+  limit: z
+    .string()
+    .optional()
+    .transform((value) => Math.min(Math.max(Number(value) || 50, 1), 100)),
+})
+export const getWorkspaceBackgroundWorkContract = defineRouteContract({
+  method: 'GET',
+  path: '/api/workspaces/[id]/background-work',
+  params: workspaceIdParamsSchema,
+  query: getWorkspaceBackgroundWorkQuerySchema,
+  response: {
+    mode: 'json',
+    schema: z.object({
+      items: z.array(backgroundWorkItemSchema),
+      /** Opaque keyset cursor for the next page; null when this page is the last. */
+      nextCursor: z.string().nullable(),
+    }),
+  },
+})
+export type BackgroundWorkItem = z.output<typeof backgroundWorkItemSchema>
+export type GetWorkspaceBackgroundWorkResponse = z.output<
+  typeof getWorkspaceBackgroundWorkContract.response.schema
+>
+
+export const rollbackForkBodySchema = z.object({
+  otherWorkspaceId: workspaceIdSchema,
+})
+export const rollbackForkContract = defineRouteContract({
+  method: 'POST',
+  path: '/api/workspaces/[id]/fork/rollback',
+  params: workspaceIdParamsSchema,
+  body: rollbackForkBodySchema,
+  response: {
+    mode: 'json',
+    schema: z.object({
+      restored: z.number().int(),
+      archived: z.number().int(),
+      unarchived: z.number().int(),
+      /** Snapshot workflows that no longer exist and couldn't be reactivated. */
+      skipped: z.number().int(),
+    }),
+  },
+})
+export type RollbackForkBody = z.input<typeof rollbackForkBodySchema>
+export type RollbackForkResponse = z.output<typeof rollbackForkContract.response.schema>
+
+export const getForkAvailabilityContract = defineRouteContract({
+  method: 'GET',
+  path: '/api/workspaces/[id]/fork/availability',
+  params: workspaceIdParamsSchema,
+  response: {
+    mode: 'json',
+    schema: z.object({
+      /** Server-evaluated verdict of the fork gate: env/plan + AppConfig rollout flag. */
+      available: z.boolean(),
+    }),
+  },
+})
+export type GetForkAvailabilityResponse = z.output<
+  typeof getForkAvailabilityContract.response.schema
+>
+
+export const unlinkForkBodySchema = z.object({
+  otherWorkspaceId: workspaceIdSchema,
+})
+export const unlinkForkContract = defineRouteContract({
+  method: 'POST',
+  path: '/api/workspaces/[id]/fork/unlink',
+  params: workspaceIdParamsSchema,
+  body: unlinkForkBodySchema,
+  response: {
+    mode: 'json',
+    schema: z.object({
+      /** False when the edge was already dissolved by a concurrent unlink (idempotent no-op). */
+      unlinked: z.boolean(),
+    }),
+  },
+})
+export type UnlinkForkBody = z.input<typeof unlinkForkBodySchema>
+export type UnlinkForkResponse = z.output<typeof unlinkForkContract.response.schema>