GET /api/v1/packages and /meta/package/<showcase> answer 500 "Converting circular structure to JSON" — the registry stores the live defineStack manifest, plugin instances included

[hotlong]

What happens

On a stock showcase boot (main @ a39b02a, objectui pin 67dadd602a3a, objectstack dev --seed-admin), signed in as the seeded admin:

GET /api/v1/packages                          -> 500 INTERNAL_ERROR
GET /api/v1/packages/com.example.showcase     -> 500 INTERNAL_ERROR
GET /api/v1/meta/package/com.example.showcase -> 500 {"error":"Internal server error"}
GET /api/v1/meta/package/com.objectstack.setup -> 200

Error body of the first two:

Converting circular structure to JSON
    --> starting at object with constructor '_ObjectQL'
    |     property 'actionActivation' -> object with constructor 'ActionActivationProjection'
    |     property 'store' -> object with constructor 'ObjectStoreActionActivationStore'
    --- property 'engine' closes the circle

Studio calls GET /api/v1/packages three times on every open and gets 500 each time (package switcher / publish surfaces read it). The 500 is not logged server-side (filed separately).

Why

• ObjectQL.registerApp(manifest) hands the app's defineStack(...) object to SchemaRegistry.installPackage(manifest) (packages/objectql/src/engine.ts ~4795), and installPackage stores that object verbatim as pkg.manifest (packages/objectql/src/registry.ts ~3575-3620).
• The showcase manifest carries live runtime plugin instances (plugins: [new ConnectorRestPlugin(), new ConnectorMcpPlugin(), MarketplaceProxyPlugin, RuntimeConfigPlugin, ...], examples/app-showcase/objectstack.config.ts ~134-162). After init those instances hold the engine.
• Since feat(actions): durable packaged-action disable — same activation ledger, dispatch-time consult #12348 (2026-08-25) the engine carries actionActivation -> store -> engine, a reference cycle, so JSON.stringify of anything that reaches the engine throws. Before that PR the same response would have serialized the entire engine graph into the payload instead of failing, which is why this only surfaces now.
• GET /packages spreads every registry item into the response as-is (packages/rest/src/package-routes.ts ~662-700, { ...item, source: 'registry' }), so one unserializable package item fails the whole list. The Setup package has no plugin instances, hence 200.

Suggested fix

1. Store a serializable manifest projection at install time: installPackage should keep the spec-shaped manifest (id, name, version, namespace, type, scope, description, dependencies, declared metadata) and drop runtime-only members such as plugin instances. The kernel keeps the live object; the registry item is a record, not the runtime.
2. GET /packages / GET /packages/:id should project explicit fields rather than spreading the item, so a future non-serializable member degrades to a missing field instead of a 500.
3. Pin it: a test that registers a package whose manifest carries an object with a reference cycle and asserts JSON.stringify(registry.getPackage(id)) succeeds, plus a route test on GET /packages over the showcase-shaped stack.

Repro

pnpm dev -- --fresh -p 3911     # showcase
curl -s -c c.txt -H 'Content-Type: application/json' -d '{"email":"admin@objectos.ai","password":"admin123"}' http://localhost:3911/api/v1/auth/sign-in/email
curl -s -b c.txt http://localhost:3911/api/v1/packages | head -c 400

Found during the objectui pin-bump dogfood (PR #14295); not caused by that bump.

Generated by Claude Code

[huangyiirene]

Triage (R+89, triage seat, session session_019kDRpB7D2XzVzkaLp57T5D): pm:queue · priority:p1 · domain:engine · type Bug.

p1: a stock showcase boot answers 500 on GET /api/v1/packages, which Studio calls three times on every open, and it has been reachable since #12348 (2026-08-25) — user-visible on the reference app, on main today.

Cross-domain single PR, designated by the triage seat (the exception path): the root cause and the defence sit in two lanes' packages, and splitting them would ship a registry that still serialises a live engine for one more round. The engine seat claims with the full file surface declared in the claim: packages/objectql/src/registry.ts (installPackage stores a spec-shaped manifest projection — id, name, version, namespace, type, scope, description, dependencies, declared metadata — and drops runtime-only members such as plugin instances; the kernel keeps the live object), packages/objectql/src/engine.ts (registerApp hand-off, if the projection lives there), and packages/rest/src/package-routes.ts (GET /packages / GET /packages/:id project explicit fields instead of spreading the item — a future non-serialisable member degrades to a missing field, never a 500). Pins per the card: a registry test with a reference-cycle-carrying manifest asserting JSON.stringify(registry.getPackage(id)) succeeds, plus a route test over the showcase-shaped stack. Not clause ②: the published response gains nothing and loses only fields that were never serialisable. Hot file: packages/objectql/src/engine.ts (the engine seat answers fold-or-serial against #14147 / #14205).

Pair: #14310 (the missing 5xx log line, domain:cli) — the same dogfood, different defect; ⛔ not folded.

Size/model suggestion: M, opus.

---

Generated by Claude Code

[hotlong]

Claim: PM loop round 1 (dogfood dispatch)
Session: session_62849a16-0144-4728-8942-9f60bb3a73f1
Branch: claude/issue-14309-packages-serializable-manifest
Worktree: objectstack-issue-14309
Domain: domain:engine (+ packages/rest seam)
File surface: packages/objectql/src/registry.ts (+ its tests), packages/rest/src/package-routes.ts, .changeset/ (stop on breach; explain in the report)
Container & model: M, model: opus, mode:subagent
Clause-②: no
Serial constraints cleared: none — no open PR touches registry.ts / package-routes.ts (checked gh pr list 2026-09-02); #14310 (5xx logging, packages/rest) is deliberately serialized AFTER this card

Maintainer direct-dispatch channel (2026-08-10 standing authorization); instruction in this session, verbatim: 「P1/P2 都开 issue，packages 500 单独修，服务先留着」 → 「使用 pm-dispatch 派发」. Dispatched by the dogfood session that filed the card, outside the lane seat; the seat holder keeps precedence on any later claim conflict.

Generated by Claude Code

[hotlong]

Claim: os-dev subagent (dispatched by the PM loop for this card)
Session: session_62849a16-0144-4728-8942-9f60bb3a73f1
Branch: claude/issue-14309-packages-serializable-manifest (empty branch pushed, write route verified)
Worktree: objectstack-issue-14309 (base f645d6f8879f5e868b8c0aac978dc0db92552739)
File surface: packages/objectql/src/registry.ts (+ its tests), packages/rest/src/package-routes.ts (+ its tests), .changeset/
Mode: mode:subagent, model opus. Clause-2: no.

Verifying the card's premise against origin/main before writing code: a real showcase boot on a random high port, the four routes from the card, and a JSON.stringify walk over registry.getPackage('com.example.showcase') to name the key that actually reaches the engine.

Generated by Claude Code

[hotlong]

Claim amendment (same session, session_62849a16-0144-4728-8942-9f60bb3a73f1, branch claude/issue-14309-packages-serializable-manifest) — one file added to the declared surface, with the measurement that forced it.

Added: packages/runtime/src/domains/packages.ts (+ a new sibling test).

Why: the card attributes the list/detail 500 to packages/rest/src/package-routes.ts. Measured on a live showcase boot, that is not the handler that answered. GET /api/v1/packages/no.such.package returns Package 'no.such.package' not found — the runtime domain's spelling; the REST twin says Package "no.such.package" was not found. And GET /api/v1/packages/com.objectstack.setup returns the installed-package record directly under data, which is deps.success(pkg) in the runtime domain; the REST twin wraps it as data.package with a source stamp.

The producer fix stays exactly where the claim put it (packages/objectql/src/registry.ts) and fixes all four routes on its own. What the added file carries is the route-level defence the triage designated — applying it only to the REST twin would ship a defence with a hole precisely where the defect was observed, so it is applied at both twins. Same defect class, same gate families, no new contract surface; packages/rest/src/package-routes.ts stays in scope and is edited as designated. No open PR touches any of the three files (checked across the 15 open PRs).

Surface now: packages/objectql/src/registry.ts, packages/runtime/src/domains/packages.ts, packages/rest/src/package-routes.ts, their tests, and .changeset/.

Generated by Claude Code