feat(objectql): opt-in sys_metadata hydration for isolated project kernels

[xuyushun441-sys]

Problem

Boot Phase-2 hydration (restoreMetadataFromDb → loadMetaFromDb, which registers objects with their fields into the SchemaRegistry) is gated on environmentId === undefined (plugin.ts). That gate assumes every project kernel sources metadata from a remote artifact / control-plane proxy and has no local sys_metadata.

That's untrue for an isolated, proxy-free project kernel that persists its OWN sys_metadata locally — the cloud single-env tenant runtime (Turso). There, objects created at runtime (e.g. via AI Studio) are not in the boot artifact manifest, so after a container restart they never re-enter the registry. registry.getObject(name) then returns nothing for them, and every registry consumer silently degrades — most visibly the engine.find() unknown-$select guard, which can no longer drop a phantom projected column and lets it zero the whole result set.

Confirmed against a live env (cloud#290): product was created at runtime, its fields are stored inline in sys_metadata, yet the guard never fired because the object wasn't in the engine registry after redeploy.

Fix

Add an explicit hydrateMetadataFromDb plugin option (default false, so the control-plane/proxy path is unchanged). When set, Phase-2 hydration runs even with environmentId defined.

Safe because:

• Each engine owns its own SchemaRegistry instance — the historical process-wide singleton is gone (engine.ts:274), so there's no cross-kernel leakage.
• loadMetaFromDb already tolerates a missing sys_metadata table (graceful no-op).

The cloud artifact-kernel-factory — documented as proxy-free with local sys_metadata and an isolated registry — opts in (separate cloud PR + SHA bump).

Tests

plugin.integration.test.ts (+2):

• a project kernel (environmentId set) without the opt-in does NOT read local sys_metadata and does NOT register the runtime object (current behavior preserved);
• with hydrateMetadataFromDb: true it hydrates and registry.getObject('product').fields contains the inline field (fails without the gate change).

Full plugin.integration.test.ts: 25 pass. Package builds + typechecks clean.

Tracks objectstack-ai/cloud#290.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
spec	Building	Preview, Comment	Jun 13, 2026 9:47pm