feat(gate): hold the overlay-whitelist table to the metadata type registry, both directions

.github/workflows/lint.yml

@@ -1101,6 +1101,23 @@ jobs:
  - name: Quick-reference section counts match their tables
  run: pnpm check:quick-reference-counts
 
+ # #11752: the "Overlay whitelist (shared-DB tenancy invariant)" table in
+ # metadata-lifecycle.mdx is a hand-kept copy of DEFAULT_METADATA_TYPE_REGISTRY
+ # sitting directly under the sentence that calls the registry the single
+ # machine-readable source. It drifted on FOUR types (flow/permission/position
+ # said ✅ against a registry that says ❌ after the #6283/#6483 rollbacks;
+ # `translation` is ✅ in the registry and had no row at all) and was caught by
+ # a human fact-checking a promo video (#11664), not by CI. The gate compares
+ # both directions — a table→registry check alone passes a table missing a
+ # whole row, which is exactly how `translation` survived — and reads the
+ # registry by AST: the same-line regex sees 26 of the 27 entries, because
+ # `datasource` opens its brace on its own line.
+ # It lives in this job with the other docs guards: the edit that breaks it is
+ # a docs edit, so a packages/** paths filter would blind it to its own
+ # failure mode.
+ - name: Overlay whitelist table matches the metadata type registry
+ run: pnpm check:overlay-whitelist-table
+
  # #9604: the runtime-services chapter's pages are enumerated in three
  # hand-written places (meta.json "pages", the chapter list in
  # runtime-services/index.mdx, the services.* table in kernel/index.mdx) and

content/docs/concepts/metadata-lifecycle.mdx

@@ -107,15 +107,17 @@ In shared-database multi-tenancy, **most metadata types must not be per-org cust
 
 | Type | `allowOrgOverride` | Rationale |
 | :--- | :---: | :--- |
-| `view`, `dashboard`, `report`, `email_template`| ✅ | Pure rendering. Per-org customization is safe. |
-| `flow` | ✅ | Per-org overlays are allowed for automation definitions. |
+| `view`, `dashboard`, `report`, `email_template`, `translation` | ✅ | Pure rendering / render-time content. Per-org customization is safe. |
+| `flow` | ❌ | Flows carry execution side-effects (events, jobs, audit), and the `flow` entry declares `supportsOverlay: false` — the loader cannot merge a per-org flow overlay, so the write permission granted a write nothing could read back: an org-scoped flow overlay wrote successfully and **lost its binding on the next cold start**. Rolled back (#6283) so the silent phantom is a loud `403 not_overridable` at the moment of the write. **`allowRuntimeCreate` stays `true`** — a tenant may still author a *brand-new* flow through the runtime API (ADR-0070 package-first authoring); what is closed is overlaying a *packaged* flow per org. |
 | `agent` | ❌ | Agents are platform-owned and closed to third parties (ADR-0063 §2) — no per-org agent fork. |
-| `permission`, `position` | ✅ | Per-org overlays are allowed; tenant-level controls layer on top. |
+| `permission`, `position` | ❌ | Authorization correctness — a per-org overlay of a packaged permission set *is* silent privilege drift (ADR-0005's security row). Rolled back from an unratified `true` by the 2026-08-08 maintainer ruling (#6483); `position` takes the amendment's `false` default for new types. **`allowRuntimeCreate` stays `true`**: runtime-created sets (including package-bound rows materialized through the metadata door) keep working, while an admin-door edit of a *code-declared* set refuses with `403 not_overridable` — edit the package and re-publish (ADR-0086 two-doors). |
 | `object` | ❌ | Defines the table schema. Overriding a packaged object would break existing data — but `allowRuntimeCreate: true`, so tenants *can* author brand-new objects, **and this is also how a new field is added** (write the object with the field in `fields`). |
 | `field` | ❌ | **Also `allowRuntimeCreate: false` since protocol 17** (#7893). A field is not a standalone artifact — fields are authored inside their object (`ObjectSchema.fields`), so a `field` write minted a *separate* `sys_metadata` row keyed `('field','<object>.<name>')` that nothing ever composed into the parent: `PUT /meta/field/showcase_task.zz_probe` answered 200 `state=active`, the row read back `_diagnostics.valid: true`, and `GET /meta/object/showcase_task` never listed the field. The door is closed rather than bridged: add a field by writing its **object** (`PUT /meta/object/:name`, or `**/*.object.ts` and redeploy), which both persists and composes. Existing rows are untouched — they were inert before the change too — and remain deletable. |
 | `datasource` | ❌ | Connection strings; multi-tenant isolation is enforced at a higher layer. (`allowRuntimeCreate: true` — the datasource wizard persists `origin: 'runtime'` rows.) |
 | `job` | ❌ | **Also `allowRuntimeCreate: false` since protocol 17** (#4509). `JobSchema.handler` names a function in the compiled bundle's function table, which a runtime writer has no way to reach — so a job created in Studio or through `PUT /meta` parsed, saved, reported success and was never scheduled. The door is closed rather than bridged: `job` stays first-class through `*.job.ts` / `defineStack({ jobs, functions })`, where every schedule shape, `retryPolicy` and `timeout` does reach the scheduler. Existing rows are untouched — they were never scheduled — and `migrateStoredMetadata` reports them `skipped`. |
 
+Those five are the **complete** `allowOrgOverride: true` set: of the 27 types in `DEFAULT_METADATA_TYPE_REGISTRY`, every other one is `false`. The ❌ rows above are the `false` types whose *second* tier (`allowRuntimeCreate`) is worth calling out; any type not listed is `allowOrgOverride: false`.
+
 There is no `workflow` metadata type (per [ADR-0020](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0020-state-machine-converge-and-enforce.md), record state machines are a `state_machine` validation). Nor is there a standalone `validation` type any more — it was retired in protocol 17 under [ADR-0088](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0088-metadata-kind-admission-and-retirement.md) because `ValidationRuleSchema` carries no object-binding key, so a rule authored through that door could never say what it protected; author rules in the object's own `validations[]` instead. The runtime gate is implemented in `OVERLAY_ALLOWED_TYPES` (derived from the registry) and enforced by `SysMetadataRepository.put()`.
 
 The gate is **two-tier** — `allowOrgOverride: false` is not the same as "no runtime writes":

package.json

@@ -47,6 +47,7 @@
  "check:template-version-sync": "node scripts/sync-template-versions.mjs --self-test",
  "check:role-word": "node scripts/check-role-word.mjs --self-test && node scripts/check-role-word.mjs",
  "check:quick-reference-counts": "node scripts/check-quick-reference-counts.mjs --self-test && node scripts/check-quick-reference-counts.mjs",
+ "check:overlay-whitelist-table": "node scripts/check-overlay-whitelist-table.mjs --self-test && node scripts/check-overlay-whitelist-table.mjs",
  "check:runtime-services-index": "node scripts/check-runtime-services-index.mjs --self-test && node scripts/check-runtime-services-index.mjs",
  "check:skill-frame-sync": "node scripts/check-skill-frame-sync.mjs --self-test && node scripts/check-skill-frame-sync.mjs",
  "check:skill-frame-freshness": "node scripts/check-skill-frame-freshness.mjs --self-test && node scripts/check-skill-frame-freshness.mjs",