feat(packages): consolidate package subsystem so AI-built app packages surface in Studio

[xuyushun441-sys]

Context

When the AI builds an app it auto-creates an app.<name> package (#1550) so the drafted artifacts have a home — but that package never appeared in Studio's package selector or detail. Root cause: the package subsystem was split across two stores that never met, with no reconciliation in either direction:

• In-memory SchemaRegistry (registry.ts) — written by boot-time registerApp() and HTTP POST /api/v1/packages. This is the only store Studio reads (its selector hits the dispatcher's /api/v1/packages, whose list = registry.getAllPackages() and detail = registry.getPackage()).
• sys_packages table (service-package) — where the AI writes (ensureAppPackage → packageService.publish). Nothing loaded it into the registry; the dispatcher never read it.

So the AI's package landed in sys_packages, Studio read the registry → invisible. And protocol.installPackage was declared in the interface but never implemented.

Change — one write primitive, one read source

• @objectstack/objectql: implement ObjectStackProtocolImplementation.installPackage — the canonical write primitive. Registers the package in the in-memory registry and best-effort persists to sys_packages via the optional package service. Non-fatal when no package service is wired (registry write still succeeds).
• @objectstack/runtime: dispatcher POST /api/v1/packages routes through protocol.installPackage (falls back to the bare registry write when the protocol is unavailable) — HTTP installs are durable too.
• @objectstack/service-package: on boot, reconcile sys_packages rows back into the registry without clobbering filesystem-registered packages — persisted packages survive a restart and stay visible.
• @objectstack/service-ai: apply_blueprint's ensureAppPackage prefers protocol.installPackage (falls back to the legacy package-service publish), so an app package lands where Studio reads it.

Verification

• Live (showcase :3000): POST /api/v1/packages (→ protocol.installPackage) returns 201, GET /api/v1/packages/<id> returns 200, and the package now appears in GET /api/v1/packages (list count 15 → 16) — the read path Studio's selector consumes.
• Unit (all green): protocol.installPackage writes registry + calls publish, skips/persists gracefully when the service is absent or rejects; dispatcher POST routes through the primitive and falls back; service-package boot-hydration hydrates a persisted row and does not overwrite an existing id; apply_blueprint prefers protocol.installPackage and falls back to publish. Full suites: objectql 491, runtime 336, service-package 2, service-ai 471. ESM/CJS/DTS builds clean.

Scope

Still the legacy package_id plane — sealed sys_package_version versioning and cross-environment promotion remain ADR-0027 follow-ups.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jun 3, 2026 12:01am