fix(docs): recursive field diff in check:openapi + the deep drift it found

A mutation test showed the doc<->contract field diff only compared
top-level properties, so a typo inside the { data } envelope passed.
The diff now descends through matching object properties and array
items (both sides must expose a property set — passthrough contracts
and prose-only docs end the descent instead of false-positive), with
the Zod JSON-schema root doubling as the $defs context.

Deep drift it immediately caught, fixed here: select-column config
(options/multiple) missing from every tables column schema, AddColumnBody
hand-rolling a third column shape (now composed from ColumnInput, with
position/workflowGroupId as the per-op extensions the contracts actually
admit), chunking strategyOptions undocumented, and the deployment
lifecycle fields (activeDeployment/latestDeploymentAttempt) missing from
DeploymentState.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CiHhAk2R1NryaS3R8n2yFz

Author: TheodoreSpeaks

apps/docs/openapi-v2-knowledge.json

@@ -1001,6 +1001,29 @@
             "type": "string",
             "description": "Chunking strategy applied during processing.",
             "enum": ["auto", "text", "regex", "recursive", "sentence", "token"]
+          },
+          "strategyOptions": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Strategy-specific tuning. `pattern`/`strictBoundaries` apply to the `regex` strategy; `separators` to `text`; `recipe` to `recursive`.",
+            "properties": {
+              "pattern": {
+                "type": "string",
+                "maxLength": 500
+              },
+              "separators": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "recipe": {
+                "enum": ["plain", "markdown", "code"]
+              },
+              "strictBoundaries": {
+                "type": "boolean"
+              }
+            }
           }
         }
       },

apps/docs/openapi-v2-tables.json

@@ -1648,6 +1648,17 @@
           "workflowGroupId": {
             "type": "string",
             "description": "Set when the column is the output of a workflow group."
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SelectOption"
+            },
+            "description": "Declared options for a `select` column; absent on other types."
+          },
+          "multiple": {
+            "type": "boolean",
+            "description": "A `select` column that accepts multiple options per cell."
           }
         }
       },
@@ -1677,6 +1688,21 @@
             "type": "boolean",
             "default": false,
             "description": "Whether values in this column must be unique across all rows."
+          },
+          "id": {
+            "type": "string",
+            "description": "Stable column id. Server-assigned — normally omit."
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SelectOption"
+            },
+            "description": "Declared options for a `select` column; absent on other types."
+          },
+          "multiple": {
+            "type": "boolean",
+            "description": "A `select` column that accepts multiple options per cell."
           }
         }
       },
@@ -1811,7 +1837,20 @@
                 "maxItems": 50,
                 "description": "Column definitions. A table must have between 1 and 50 columns.",
                 "items": {
-                  "$ref": "#/components/schemas/ColumnInput"
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ColumnInput"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "workflowGroupId": {
+                          "type": "string",
+                          "description": "Advanced: binds the column to a workflow group's output."
+                        }
+                      }
+                    }
+                  ]
                 }
               }
             }
@@ -1833,38 +1872,22 @@
             "description": "The workspace that owns the table."
           },
           "column": {
-            "type": "object",
-            "description": "The column definition to add.",
-            "required": ["name", "type"],
-            "properties": {
-              "name": {
-                "type": "string",
-                "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-                "maxLength": 50,
-                "description": "Column name. Starts with a letter or underscore; contains only alphanumerics and underscores.",
-                "example": "phone"
-              },
-              "type": {
-                "type": "string",
-                "enum": ["string", "number", "boolean", "date", "json"],
-                "description": "Data type of the column."
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ColumnInput"
               },
-              "required": {
-                "type": "boolean",
-                "default": false,
-                "description": "Whether the column requires a value on insert."
-              },
-              "unique": {
-                "type": "boolean",
-                "default": false,
-                "description": "Whether values in this column must be unique across all rows."
-              },
-              "position": {
-                "type": "integer",
-                "minimum": 0,
-                "description": "Zero-based insert position in the column order. Appended at the end when omitted."
+              {
+                "type": "object",
+                "properties": {
+                  "position": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Zero-based insert position in the column order. Appended at the end when omitted."
+                  }
+                }
               }
-            }
+            ],
+            "description": "The column definition to add."
           }
         }
       },
@@ -1906,6 +1929,17 @@
               "unique": {
                 "type": "boolean",
                 "description": "Whether values in this column must be unique across all rows."
+              },
+              "options": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/SelectOption"
+                },
+                "description": "Declared options for a `select` column; absent on other types."
+              },
+              "multiple": {
+                "type": "boolean",
+                "description": "A `select` column that accepts multiple options per cell."
               }
             }
           }
@@ -2428,6 +2462,21 @@
             "description": "Operand. Omit for the `is*` operators. Ranges on `number` columns require numbers, on `date` columns ISO strings (compared as UTC, independent of any session timezone); ranges on `boolean`/`json` columns are rejected."
           }
         }
+      },
+      "SelectOption": {
+        "type": "object",
+        "required": ["id", "name"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable option id — the value stored in cells."
+          },
+          "name": {
+            "type": "string",
+            "maxLength": 100,
+            "description": "Display name. Filters on select columns accept names (resolved case-insensitively)."
+          }
+        }
       }
     },
     "responses": {

apps/docs/openapi-v2-workflows.json

@@ -937,7 +937,14 @@
       "DeploymentState": {
         "type": "object",
         "description": "Base deployment state shared by deploy, undeploy, and rollback results.",
-        "required": ["id", "isDeployed", "deployedAt", "warnings"],
+        "required": [
+          "id",
+          "isDeployed",
+          "deployedAt",
+          "warnings",
+          "activeDeployment",
+          "latestDeploymentAttempt"
+        ],
         "properties": {
           "id": {
             "type": "string",
@@ -961,6 +968,14 @@
             "items": {
               "type": "string"
             }
+          },
+          "activeDeployment": {
+            "type": ["object", "null"],
+            "description": "Summary of the currently live deployment version, or null when none is active."
+          },
+          "latestDeploymentAttempt": {
+            "type": ["object", "null"],
+            "description": "Lifecycle status of the most recent deploy attempt (preparing/activating/active/failed/superseded) — poll this to a terminal state; deploys admit asynchronously, so HTTP success only means the attempt was accepted."
           }
         }
       },

scripts/check-openapi-specs.ts

@@ -155,11 +155,6 @@ function docPropertyNames(schema: unknown, spec: Json): Set<string> | null {
   return null
 }
 
-/** Same union logic over the Zod-derived JSON schema (no `$ref`s inside). */
-function zodPropertyNames(schema: unknown): Set<string> | null {
-  return docPropertyNames(schema, {} as Json)
-}
-
 function toJsonSchema(schema: z.ZodType, io: 'input' | 'output'): Json | null {
   try {
     return z.toJSONSchema(schema, { io, unrepresentable: 'any' }) as Json
@@ -285,6 +280,104 @@ function checkQueryParams(operation: Operation, contract: ContractLike, name: st
   }
 }
 
+/** Property subschema lookup, searching `oneOf`/`anyOf`/`allOf` variants. */
+function propertyNode(schema: unknown, root: Json, prop: string): unknown {
+  const node = deref(schema, root)
+  if (!node || typeof node !== 'object') return undefined
+  const record = node as Json
+  const variants = (record.oneOf ?? record.anyOf ?? record.allOf) as unknown[] | undefined
+  if (variants) {
+    for (const variant of variants) {
+      const found = propertyNode(variant, root, prop)
+      if (found !== undefined) return found
+    }
+    return undefined
+  }
+  return (record.properties as Json | undefined)?.[prop]
+}
+
+/** Deref + step through array wrappers so item objects compare directly. */
+function unwrapArrays(node: unknown, root: Json): unknown {
+  let current = deref(node, root)
+  for (let i = 0; i < 3; i++) {
+    const record = current as Json | null
+    if (record && typeof record === 'object' && record.type === 'array' && record.items) {
+      current = deref(record.items, root)
+    } else {
+      break
+    }
+  }
+  return current
+}
+
+interface DiffContext {
+  specFile: string
+  label: string
+  name: string
+  where: 'body' | 'response'
+}
+
+/**
+ * Recursively diffs property-name sets between the Zod-derived JSON schema and
+ * the documented one, descending through matching object properties and array
+ * items. Comparison happens only where BOTH sides expose a property set — an
+ * opaque side (records, `additionalProperties`, prose-only docs) ends the
+ * descent instead of producing false positives. The Zod root doubles as the
+ * `$defs` resolution context for recursive schemas.
+ */
+function diffSchemaFields(
+  zodNode: unknown,
+  zodRoot: Json,
+  docNode: unknown,
+  docRoot: Json,
+  ctx: DiffContext,
+  prefix: string,
+  depth: number
+): void {
+  if (depth > 4) return
+  const zodObj = unwrapArrays(zodNode, zodRoot)
+  const docObj = unwrapArrays(docNode, docRoot)
+  const zodNames = docPropertyNames(zodObj, zodRoot)
+  const docNames = docPropertyNames(docObj, docRoot)
+  if (!zodNames || !docNames) return
+  const fieldPath = (n: string) => (prefix ? `${prefix}.${n}` : n)
+  /**
+   * A `.passthrough()` contract deliberately under-declares its fields, so the
+   * docs are allowed to document more than the Zod side names.
+   */
+  const extra = (zodObj as Json).additionalProperties
+  const zodIsPassthrough =
+    extra === true || (!!extra && typeof extra === 'object' && Object.keys(extra).length === 0)
+  for (const n of zodNames) {
+    if (!docNames.has(n)) {
+      fail(
+        ctx.specFile,
+        `${ctx.label}: ${ctx.where} field "${fieldPath(n)}" (${ctx.name}) not documented`
+      )
+    }
+  }
+  for (const n of docNames) {
+    if (!zodNames.has(n) && !zodIsPassthrough) {
+      fail(
+        ctx.specFile,
+        `${ctx.label}: documented ${ctx.where} field "${fieldPath(n)}" does not exist on ${ctx.name}`
+      )
+    }
+  }
+  for (const n of zodNames) {
+    if (!docNames.has(n)) continue
+    diffSchemaFields(
+      propertyNode(zodObj, zodRoot, n),
+      zodRoot,
+      propertyNode(docObj, docRoot, n),
+      docRoot,
+      ctx,
+      fieldPath(n),
+      depth + 1
+    )
+  }
+}
+
 function checkBodyAndResponse(operation: Operation, contract: ContractLike, name: string): void {
   const { specFile, path: p, method, op, spec } = operation
   const label = `${method.toUpperCase()} ${p}`
@@ -293,17 +386,17 @@ function checkBodyAndResponse(operation: Operation, contract: ContractLike, name
     'application/json'
   ] as Json | undefined
   if (contract.body && docBodySchema?.schema) {
-    const zodNames = zodPropertyNames(toJsonSchema(contract.body, 'input'))
-    const docNames = docPropertyNames(docBodySchema.schema, spec)
-    if (zodNames && docNames) {
-      for (const n of zodNames) {
-        if (!docNames.has(n)) fail(specFile, `${label}: body field "${n}" (${name}) not documented`)
-      }
-      for (const n of docNames) {
-        if (!zodNames.has(n)) {
-          fail(specFile, `${label}: documented body field "${n}" does not exist on ${name}`)
-        }
-      }
+    const zodRoot = toJsonSchema(contract.body, 'input')
+    if (zodRoot) {
+      diffSchemaFields(
+        zodRoot,
+        zodRoot,
+        docBodySchema.schema,
+        spec,
+        { specFile, label, name, where: 'body' },
+        '',
+        0
+      )
     }
   }
 
@@ -313,19 +406,17 @@ function checkBodyAndResponse(operation: Operation, contract: ContractLike, name
     const docResponse = successCode ? (deref(responses[successCode], spec) as Json) : undefined
     const docSchema = ((docResponse?.content as Json)?.['application/json'] as Json)?.schema
     if (docSchema) {
-      const zodNames = zodPropertyNames(toJsonSchema(contract.response.schema, 'output'))
-      const docNames = docPropertyNames(docSchema, spec)
-      if (zodNames && docNames) {
-        for (const n of zodNames) {
-          if (!docNames.has(n)) {
-            fail(specFile, `${label}: response field "${n}" (${name}) not documented`)
-          }
-        }
-        for (const n of docNames) {
-          if (!zodNames.has(n)) {
-            fail(specFile, `${label}: documented response field "${n}" does not exist on ${name}`)
-          }
-        }
+      const zodRoot = toJsonSchema(contract.response.schema, 'output')
+      if (zodRoot) {
+        diffSchemaFields(
+          zodRoot,
+          zodRoot,
+          docSchema,
+          spec,
+          { specFile, label, name, where: 'response' },
+          '',
+          0
+        )
       }
     }
   }