feat: update documentation and tests to reflect removal of metadata DB bridge in ObjectOS

Author: hotlong

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **M1 — Project Artifact envelope schema (`@objectstack/spec`)** — Introduced the v0 `ProjectArtifactSchema` in `packages/spec/src/system/project-artifact.zod.ts`, the immutable envelope that `objectstack compile` will produce and ObjectOS will consume at boot. Required fields: `schemaVersion` (literal `'0.1'`), `projectId`, `commitId`, `checksum` (`{ algorithm, value }`), `metadata` (per-category arrays, `passthrough()` for forward compatibility), `functions` (inlined source with optional language/source/hash), and `manifest` (plugin / driver / engine requirements). Optional `builtAt`, `builtWith`, and a reserved `payloadRef` (`{ url, expiresAt, checksum }`) for future S3 indirection without an envelope bump. 14 new tests in `project-artifact.test.ts`. Resolves ROADMAP M1; unblocks M3 (Artifact API) and M4 (ObjectOS artifact loader).
 
 ### Changed
+- **D1 — ObjectOS metadata DB bridge removed** — `MetadataPlugin` no longer registers `sys_metadata` / `sys_metadata_history` into the ObjectOS manifest and no longer auto-bridges ObjectQL to `DatabaseLoader` during `start()`. Runtime metadata is now file/artifact backed; database-backed metadata persistence remains an explicit `MetadataManager` capability for control-plane services. Updated ROADMAP, North Star, Metadata Service docs, and ObjectStack skills to reflect the boundary.
 - **D5 — `ManifestSchema.scope` enum trimmed to `'cloud' | 'system' | 'project'`** — Removed the deprecated `'platform'` and `'environment'` aliases from `packages/spec/src/kernel/manifest.zod.ts`. No call site in the workspace was setting the deprecated values, so this is a clean break. Resolves ROADMAP D5.
 - **D4 — `ObjectSchemaBase.namespace` removed** — Object identity is now single-sourced on `name`. The deprecated `namespace` field has been removed from `ObjectSchemaBase` (`packages/spec/src/data/object.zod.ts`); legacy inputs that still set `namespace` are silently stripped by Zod's default object behavior. Package-level namespace (FQN computation, marketplace publishing, `DatasourceRoutingRule.namespace`) is intentionally retained as an internal mechanic. Five legacy `ObjectSchema namespace` test blocks were rewritten as a single `name-as-identity` block. Resolves ROADMAP D4.
 - **D7 — Plugin manifest header + objects unified per package** — Each plugin / service now exposes a single canonical `src/manifest.ts` file that both `objectstack.config.ts` (compile-time) and the runtime `*-plugin.ts` (`manifest.register()`) import from. This eliminates a real divergence in `plugin-auth` and `plugin-security` whose configs imported from a non-existent `./src/objects/` directory and silently shipped empty object lists at compile time while their runtime registrations were intact. Affected packages: `@objectstack/plugin-auth`, `@objectstack/plugin-security`, `@objectstack/service-tenant`. Resolves ROADMAP D7.

ROADMAP.md

@@ -1,6 +1,6 @@
 # ObjectStack - Road Map
 
-> **Last Updated:** 2026-04-26 (Phase 1 foundation: M1 + D4 + D5 + D7 landed)
+> **Last Updated:** 2026-04-26 (Phase 1 foundation: M1 + D1 + D4 + D5 + D7 landed)
 > **Authoritative Spec:** [content/docs/concepts/north-star.mdx](content/docs/concepts/north-star.mdx) - §7 Alignment Check is the single source of truth for Built / Drift / Missing.
 > This file is the **actionable checklist** derived from that ledger. When north-star §7 changes, update this file too.
 
@@ -49,33 +49,14 @@ Code that exists and matches the intended architecture. Do not regress these.
 | JSON-payload metadata column (`sys_metadata.metadata` textarea) | [packages/metadata/src/objects/sys-metadata.object.ts](packages/metadata/src/objects/sys-metadata.object.ts) |
 | CLI `publish` - local JSON -> remote server wire (endpoint shape still wrong, see D2) | [packages/cli/src/commands/publish.ts](packages/cli/src/commands/publish.ts) |
 | **M1** Project Artifact envelope schema (`schemaVersion / projectId / commitId / checksum / metadata / functions / manifest`) | [packages/spec/src/system/project-artifact.zod.ts](packages/spec/src/system/project-artifact.zod.ts) |
+| **D1** ObjectOS metadata DB bridge removed - `MetadataPlugin` no longer registers `sys_metadata` / `sys_metadata_history` or auto-bridges ObjectQL to `DatabaseLoader` | [packages/metadata/src/plugin.ts](packages/metadata/src/plugin.ts) |
 
 ---
 
 ## 🟡 Drift (Needs Cleanup)
 
 Existing code that contradicts the intended Phase 1 architecture. Fix these before building new surface area that depends on them.
 
-### D1 - 🟡 MetadataPlugin maintains a DB bridge in ObjectOS (Biggest Drift)
-
-**Priority: P0.** The primary startup read has been partially fixed — `local-file` mode (M1.x) lets ObjectOS boot from `dist/objectstack.json` without touching any database. However, [packages/metadata/src/plugin.ts](packages/metadata/src/plugin.ts) still:
-
-1. Registers `SysMetadataObject` and `SysMetadataHistoryObject` into the **ObjectOS** manifest — these tables belong only in `apps/cloud` (control plane).
-2. Bridges ObjectQL to a `DatabaseLoader` via `setDataEngine()` after startup — subsequent `metadata.register()` writes persist metadata to `sys_metadata` in the project DB, and `metadata.list()` / `get()` aggregate from it.
-
-Under Phase 1 the project DB contains **business rows only**. Metadata lives in the control plane and is delivered to ObjectOS as an immutable artifact. The DB bridge breaks that boundary and undermines the `commitId` + `checksum` immutability guarantee — `sys_metadata` rows in the project DB may diverge from the published artifact.
-
-**What is already done:**
-- `local-file` artifact mode — ObjectOS boots from `dist/objectstack.json` without any DB read (M1.x). ✅
-
-**Remaining fix path:**
-1. Remove `SysMetadataObject` / `SysMetadataHistoryObject` registration from `MetadataPlugin.init()` — these tables belong in `apps/cloud` only.
-2. Remove the `setDataEngine()` / `DatabaseLoader` bridge from `MetadataPlugin.start()` — ObjectOS metadata is read-only (artifact → kernel); history and versioning are control-plane concerns.
-3. Implement the Artifact API endpoint (M3) and swap `MetadataPlugin`'s source to HTTP fetch (M4).
-4. Confirm `sys_metadata` is absent from the project DB schema after the D8 split into `apps/cloud` + `apps/server`.
-
-**Depends on:** M3, M4. **Prerequisite for:** D8 clean split.
-
 ### D2 - `objectstack publish` uses legacy `/api/v1/packages` endpoint
 
 [packages/cli/src/commands/publish.ts](packages/cli/src/commands/publish.ts) POSTs a "package" payload that is not the Phase 1 project metadata endpoint.
@@ -204,7 +185,7 @@ Tests: [packages/spec/src/system/project-artifact.test.ts](packages/spec/src/sys
 - [ ] Data migration script for existing installations.
 - [ ] Keep project DBs for business rows only.
 
-**Prerequisite for:** M3, D1 fix, D3.
+**Prerequisite for:** M3, D3.
 
 ### M3 - Project Artifact API endpoint
 
@@ -214,16 +195,16 @@ Tests: [packages/spec/src/system/project-artifact.test.ts](packages/spec/src/sys
 - [ ] Response includes `commitId` and `checksum`.
 - [ ] Reserve response shape for future `{ url, expiresAt, checksum }` indirection, but do not build S3 yet.
 
-**Prerequisite for:** M4, D1 fix.
+**Prerequisite for:** M4.
 
 ### M4 - ObjectOS artifact loader
 
-- [ ] Swap `MetadataPlugin` data source: project-DB reads -> HTTP fetch against Artifact API.
+- [ ] Add `MetadataPlugin` production source: HTTP fetch against Artifact API.
 - [ ] Validate artifact with Zod before hydrating kernel.
 - [ ] Local artifact cache with durability across control-plane outages.
 - [ ] Cache key by `projectId` + `commitId`/`checksum`.
 
-**Resolves:** D1.
+**Completes:** production ObjectOS artifact source.
 
 ### M5 - Project publish endpoint
 
@@ -306,7 +287,7 @@ M1 Artifact format v0
 ├── M1.x Runtime Inputs 边界化 (Artifact + Deployment Config 分离)
 └── M2 Metadata migration to control plane
     ├── M3 Project Artifact API
-    │   └── M4 ObjectOS artifact loader -> resolves D1
+    │   └── M4 ObjectOS artifact loader
     └── M5 Project publish endpoint -> resolves D2
         └── M6 Studio metadata/artifact viewer
 
@@ -327,4 +308,4 @@ D8 split apps/cloud + apps/server(after M3/M4 make ObjectOS standalone)
 | [.github/copilot-instructions.md](.github/copilot-instructions.md) | Mirror of CLAUDE.md for Copilot |
 | [packages/cli/src/commands/compile.ts](packages/cli/src/commands/compile.ts) | TS -> JSON compile (Built anchor) |
 | [packages/cli/src/commands/publish.ts](packages/cli/src/commands/publish.ts) | Publish command (Drift D2 target) |
-| [packages/metadata/src/plugin.ts](packages/metadata/src/plugin.ts) | MetadataPlugin (Drift D1 target) |
+| [packages/metadata/src/plugin.ts](packages/metadata/src/plugin.ts) | MetadataPlugin (artifact/local-file metadata loader; D1 resolved anchor) |

content/docs/concepts/implementation-status.mdx

@@ -65,12 +65,13 @@ This matrix is generated from actual codebase analysis and represents the curren
 ### Metadata Framework
 
 <Callout type="info">
-**Degraded Status** — Metadata is an in-memory registry framework. Database persistence for metadata storage is not yet implemented. Discovery reports this service as `degraded`.
+**Runtime Boundary** — ObjectOS metadata is file/artifact-backed and read-only at boot. Database-backed metadata persistence exists for explicitly configured control-plane services, not as an automatic ObjectOS project-DB bridge.
 </Callout>
 
 - Metadata API (list types, list items, get item) is fully functional
-- Metadata is loaded from config files at startup and held in memory
-- Future: metadata persistence to database for runtime modifications
+- Metadata is loaded from config files or `dist/objectstack.json` at startup and held in memory
+- `MetadataPlugin` no longer registers `sys_metadata` / `sys_metadata_history` into ObjectOS or auto-bridges ObjectQL to `DatabaseLoader`
+- Future: production Artifact API loader and durable local artifact cache
 
 ### System Services
 

content/docs/concepts/north-star.mdx

@@ -169,9 +169,10 @@ data rows.
 
 **Status:** Multi-project kernel + hostname routing built. `local-file` artifact
 boot (M1.x) implemented — ObjectOS can boot from `dist/objectstack.json` without
-any DB read. Remaining drift: `MetadataPlugin` still bridges ObjectQL to a
-`DatabaseLoader` after startup, persisting metadata to and reading from the
-project DB. This is D1. See [packages/runtime/src/project-kernel-factory.ts](packages/runtime/src/project-kernel-factory.ts)
+any DB read. D1 is resolved: `MetadataPlugin` no longer registers
+`sys_metadata` / `sys_metadata_history` into the ObjectOS manifest and no longer
+auto-bridges ObjectQL to `DatabaseLoader` after startup. See
+[packages/runtime/src/project-kernel-factory.ts](packages/runtime/src/project-kernel-factory.ts)
 and [packages/metadata/src/plugin.ts](packages/metadata/src/plugin.ts).
 
 ## 4. Core Entity Hierarchy
@@ -201,7 +202,7 @@ Organization                            <- control plane
 | :----- | :--------------- | :----- |
 | Organization | Control plane `sys_organization` | Built |
 | Project | Control plane `sys_project` (hostname binding) | Built |
-| Metadata State | Control-plane metadata payloads + project revision (`commit_id`, checksum), scoped by `organization_id` + `project_id` | Partially fixed: startup read now artifact-based (M1.x); `DatabaseLoader` bridge still persists metadata to project DB post-startup (D1) |
+| Metadata State | Control-plane metadata payloads + project revision (`commit_id`, checksum), scoped by `organization_id` + `project_id` | ObjectOS DB bridge removed (D1); control-plane migration still tracked by M2 |
 | Artifact | `GET /api/v1/apps/:projectId/artifact` response | To build |
 | Business DB | Per-project dedicated DB (Turso / SQL / memory) | Built (driver provisioning), but currently shares space with metadata |
 | Branch / Release | Future control-plane entities | Deferred |
@@ -326,7 +327,7 @@ identity would require federated auth, which is out of scope.
 - Per-project kernel factory: [packages/runtime/src/project-kernel-factory.ts](packages/runtime/src/project-kernel-factory.ts)
 - HTTP dispatch: [packages/runtime/src/http-dispatcher.ts](packages/runtime/src/http-dispatcher.ts)
 - Org-scoped proxy: [packages/runtime/src/control-plane-proxy-driver.ts](packages/runtime/src/control-plane-proxy-driver.ts)
-- Metadata loading (startup read fixed for `local-file` mode; DB bridge still persists to project DB post-startup — D1): [packages/metadata/src/plugin.ts](packages/metadata/src/plugin.ts)
+- Metadata loading (artifact/local-file backed; no automatic ObjectQL -> `DatabaseLoader` bridge in ObjectOS): [packages/metadata/src/plugin.ts](packages/metadata/src/plugin.ts)
 - App catalog sync: [packages/services/service-tenant/src/services/app-catalog.service.ts](packages/services/service-tenant/src/services/app-catalog.service.ts)
 
 ## 6. Key Lifecycles
@@ -457,23 +458,12 @@ reduce Drift, and advance Missing.
 - **TS -> JSON compile pipeline.** `objectstack compile` validates a local TS stack against `ObjectStackDefinitionSchema` and writes `dist/objectstack.json` - [packages/cli/src/commands/compile.ts](packages/cli/src/commands/compile.ts).
 - **Zod -> JSON Schema publishing pipeline.** The bridge that makes TS/JSON interchangeable - [packages/spec/scripts/build-schemas.ts](packages/spec/scripts/build-schemas.ts).
 - **Scaffolded TS file tree.** `create-objectstack` emits a `defineStack()` entry point plus split-out `src/objects/*.ts`, `src/views/*.ts` etc. - [packages/create-objectstack/src/index.ts](packages/create-objectstack/src/index.ts).
+- **ObjectOS metadata DB bridge removed.** `MetadataPlugin` no longer registers `sys_metadata` / `sys_metadata_history` into the ObjectOS manifest and no longer auto-connects ObjectQL to a `DatabaseLoader`; runtime metadata is hydrated from files or artifacts only - [packages/metadata/src/plugin.ts](packages/metadata/src/plugin.ts).
 - **JSON-payload metadata storage.** `sys_metadata.metadata` column is already a textarea-shaped JSON payload column - [packages/metadata/src/objects/sys-metadata.object.ts](packages/metadata/src/objects/sys-metadata.object.ts). (The *location* of the table still needs to move to the control plane - see Drift.)
 - **CLI `publish` link.** The end-to-end "local JSON -> remote server" wire is alive, even though the endpoint shape is wrong - [packages/cli/src/commands/publish.ts](packages/cli/src/commands/publish.ts).
 
 ### <AlertTriangle className="inline" /> Drift (Needs Cleanup)
 
-- **Biggest drift: `MetadataPlugin` maintains a DB bridge in ObjectOS.**
-  The primary startup read has been partially fixed — `local-file` mode (M1.x)
-  lets ObjectOS boot from `dist/objectstack.json` without any DB read. However,
-  [packages/metadata/src/plugin.ts](packages/metadata/src/plugin.ts) still
-  registers `sys_metadata`/`sys_metadata_history` tables into the ObjectOS
-  manifest and bridges ObjectQL to a `DatabaseLoader` after startup. This means
-  subsequent `metadata.register()` writes persist to `sys_metadata` in the
-  project DB, and `metadata.list()` / `get()` aggregate from it. Under Phase 1,
-  the project DB must contain **business rows only** — metadata lives in the
-  control plane, delivered via the Artifact API as an immutable artifact. The DB
-  bridge breaks the `commitId` / `checksum` immutability guarantee: project DB
-  rows may silently diverge from the published artifact.
 - **`env_id` should be removed from metadata storage.** In Phase 1 metadata is
   scoped by `organization_id` + `project_id`; deployment target differences are
   runtime/deployment configuration, not metadata row partitioning. Branch-like
@@ -502,13 +492,11 @@ reduce Drift, and advance Missing.
 
 ### <Globe className="inline" /> Missing (Not Started)
 
-- **Artifact format v0** - Zod schema for `{ schemaVersion, projectId, commitId, checksum, metadata, functions, manifest }`.
 - **Metadata migration to control plane** - move user metadata out of project DBs into the control-plane DB, scoped by `organization_id` + `project_id`.
 - **Project Artifact API** - `GET /api/v1/apps/:projectId/artifact` assembles the current project metadata + inlined function code into a single consumable blob, with content hash/ETag for cache validation.
-- **ObjectOS artifact loader** - swap `MetadataPlugin`'s data source from project-DB reads to HTTP fetch against the Artifact API; add local artifact cache with durability across control-plane outages.
+- **ObjectOS Artifact API loader** - add the production HTTP fetch source for `MetadataPlugin` and local artifact cache durability across control-plane outages.
 - **Project publish endpoint** - `POST /api/v1/apps/:projectId/metadata` receives compiled JSON, validates with Zod, writes the current project metadata state, and returns `commitId` + checksum.
 - **Studio metadata/artifact viewer** - browse published metadata, artifact envelope, commit id, checksum, publish history, logs, and runtime health. No metadata editing.
-- **`objectstack dev` offline boot path** - `from-local-file` kernel boot. ObjectOS reads `dist/objectstack.json` (or an in-memory TS definition) and runs fully without a control-plane connection.
 - **UI auto-generation** - artifact schemas -> Amis/React components without hand-wiring.
 
 ## 8. Non-Goals and Anti-Patterns