docs(maintenance): runbook for database-only columns after an upgrade; 17.0 __search is a false positive (#528)

[yinlianghui]

Description

Adds a §3.1 "Destructive schema drift — database-only columns after an upgrade" section to docs/MAINTENANCE.md, right after the platform-upgrade checklist it extends. os migrate plan can report columns that exist in the database but are not described by any metadata it can see; this section covers how to tell a genuine orphan from a live column the planner simply cannot vouch for, and the safe --allow-destructive procedure for the former.

Important

This PR changed direction after #528 was reclassified. The original version documented the 9 __search columns as orphans and walked operators through dropping them. Column-level verification (recorded in #528) showed they are live pinyin search-companion columns provisioned by the dev runtime — the database built by objectstack dev has 34 columns on crm_task including __search, the one built by os migrate plan --database-url <new file> has 33 without it, and migrate reports 0 destructive changes against the database it built itself. The report is a schema-view mismatch between the migrate CLI and the dev runtime, filed upstream as objectstack#3955.

Following the original runbook would have dropped working search columns, and its own safety check would not have caught it: the section named those exact columns as expected-to-drop, so "is this a column backing a field you still declare?" cleared them. The section now records the __search class as a known false positive — do not touch until #3955 lands, and the plan-review step gained a second test (is this a runtime-provisioned companion column?) plus a concrete proof technique (diff the plan against a freshly created database from the same artifact).

The cleanup itself is a runtime operation run against each deployed database during a maintenance window, so the repo deliverable is the runbook, not a code change.

Sourcing note. #528 points at docs/upgrade-17/test-report.md on branch upgrade/objectstack-17. That branch exists on this remote and is deliberately kept PR-less — it carries only the 17.0 adaptation and is blocked on 17.0 GA plus objectstack#3912/#3913/#3914. Its report records the count but does not itemise the columns, so the section names the five objects from the issue and defers to each database's own os migrate plan output.

Scope note. This is the one item from the 17.0-rc test round that is not a pre-existing 16.x defect — it only appears after a database has been upgraded to 17.0. It is merged ahead of the upgrade so the procedure (and the warning) are in place when it lands. Documentation only; changes no application behaviour.

Type of Change

• Documentation

Checklist

• Documentation updated (docs/MAINTENANCE.md)
• Changeset added (empty frontmatter — releases nothing)
• No application code touched

Refs #528 — the issue stays open, blocked on
objectstack#3955.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Jul 30, 2026 9:37am

[yinlianghui]

CI red on Build and Test (22.x) — the failure is on the base branch, not this PR.

objectstack validate fails on current main (7f0b3ef) with the same 4 errors CI shows here:

✗ Permission 'marketing_user' grants on object 'crm_competitor' which is not defined in objects.
✗ Permission 'sales_manager' grants on object 'crm_competitor' which is not defined in objects.
✗ Permission 'sales_rep' grants on object 'crm_competitor' which is not defined in objects.
✗ Permission 'system_admin' grants on object 'crm_competitor' which is not defined in objects.

Root cause is a semantic conflict between two of today's merges:

• revert: remove demo-only contract kanban and competitor module (#532 follow-up) #551 (d97f3a0) removed the demo-only competitor module, deleting src/objects/competitor.object.ts and its index.ts export.
• fix(security): grant the six objects that had no permissions at all (#488) #547 (bdad2b2, merged after) added permission grants on crm_competitor to the four profile files (src/profiles/{system-admin,sales-manager,sales-rep,marketing-user}.profile.ts) — authored while the object still existed (Authorization gaps: forecast, knowledge article and all three detail objects have no profile grants #488).

Neither PR conflicted textually, so both merged green, but their combination leaves main granting on an object that no longer exists. Every PR's merge-ref CI now inherits the failure — this PR is markdown-only and validates green standalone (verified on the exact head commit, including under CI's Node 22.23.1). The fix belongs on main: drop the stale crm_competitor grants from the four profiles (or restore the object, if the removal wasn't meant to outlive #547).

Will merge main into this branch and re-run CI once the base is green.

---

Generated by Claude Code