fix(serialization): surface @computed scalars on default reads + guard cyclic @enumerable serialization (#1484)

[kriszyp]

Closes #1484.

Problem

REST GET silently omits @computed attributes on the default (no-select) read: their getters are installed non-enumerable, and JSON.stringify only serializes own-enumerable properties (it skips inherited getters). Naively flipping computed getters to enumerable is the wrong lever:

• It installs a toJSON that does for..in over the entire struct prototype chain, eagerly invoking every enumerable getter per record — 3.4×–32× slower, scaling worse with chain depth (benchmarked).
• Non-enumerability is currently the only thing preventing @enumerable relationship cycles from overflowing the stack — there is no visited-set anywhere. @relationship @enumerable on both sides of a cycle already stack-overflows today.

Fix

Both concerns are unified in the struct toJSON, installed only when a table has an @enumerable attribute or a non-table @computed attribute (plain tables keep the raw-struct fast path and never pay a cost):

• Bounded enumeration — own keys + a precomputed name list (@enumerable attributes ∪ @computed attributes whose type is not a table type), replacing the for..in. Verified equivalent: msgpackr struct prototypes carry zero enumerable inherited props, so for..in yielded exactly this set.
• Cycle guard — @enumerable table-typed attributes form an edge graph; detectCyclicEnumerable (lazy, memoized, self-loop aware) flags tables that can cycle. Those take a path-scoped, id-keyed guard (Map<tableClass, Set<idKey>>): a record already on the current serialization path collapses to a { [primaryKey]: id } reference stub. resolveStructForJSON fully resolves nested structs so none escape to native JSON.stringify after unwind. Acyclic-enumerable tables keep a guard-free fast path. A one-time warn fires when a cyclic-enumerable schema is detected.

Table-typedness keys off the attribute definition (set early) rather than .tableClass (assigned later — unset for self/forward refs at collection time); tableClass is resolved lazily at first serialization. Composite/array primary keys are normalized (JSON.stringify) for the visited set. Name lists rebuild on schema reload (updatedAttributes() re-runs). Tables with an unconstrained (Any/untyped) @computed take the guarded path, since such a resolver can return a live cyclic entity the static graph can't see.

Note: select(computedField) already returned computed fields correctly — the bug was purely the no-select / * path.

Tests

integrationTests/resources/computed-and-cyclic-serialization.test.ts (real Harper + RocksDB + REST), 4/4:

• A1 — computed scalar surfaced on default GET.
• B1 — mutual Author↔Book @enumerable cycle → {id} stub, no overflow.
• B2 — self-referential Category.parent tree → stub, no overflow.
• B3 — unconstrained Any @computed returning a live entity (A→B→A) → stub, no overflow (exercises the guarded-path routing).

Cross-model review (Codex + Gemini + Harper domain)

Adjudicated; all findings addressed in-tree before this PR:

• Blocker (Codex+Gemini): self/forward-ref detection read .tableClass before assignment → fixed (definition-based, lazy resolution).
• Significant (Codex): composite/array PK broke the id-keyed Set → fixed (normalized key).
• Significant (Codex+Gemini): resolveStructForJSON didn't recurse plain objects → fixed.
• Significant (Gemini): schema-reload accumulation of the name lists → fixed (reset in updatedAttributes()).
• Significant (Codex+Gemini): untyped @computed returning a runtime-cyclic struct was a new exposure on the fast path (a computed-scalar-only table installed no toJSON on main, so it couldn't overflow before) → fixed (routed through the guarded path; covered by test B3).
• Concurrency of the module-level guard confirmed safe (synchronous toJSON, per-worker, torn down in finally within one frame).

[gemini-code-assist]

Code Review

This pull request addresses issue #1484 by surfacing computed scalar attributes on default reads and introducing a cycle guard for cyclic-enumerable serialization to prevent stack overflows. The review feedback points out critical issues in the serialization guard implementation, specifically a potential global state leak on error and a crash when serializing composite primary keys containing BigInt values. It also suggests using optional chaining in test assertions to avoid masking server errors.

[claude]

Reviewed; no blockers found.

Both prior findings are resolved: basicREST-test.mjs:243 now expects 288 and cache-test.mjs strips ageInMonths before the PUT (commit 620926948). The new hasSurfacedComputed guard (widened from Any-only to all non-table @computed regardless of declared scalar type) is correct, and B4 covers the typed-scalar-returning-live-entity case.

[Ethan-Arrowood]

Code looks right, but the unit failures are this PR's: the basicREST computed-index assertion asserts the pre-fix behavior and needs updating, cache-test's 400 needs a look, and the new test imports node:assert/strict which lint now rejects (#1753). Happy to approve once CI is green.

_{sent with Claude Fable 5}

[kriszyp]

CI was red on 3 things after the rebase — pushed fixes for the two that were real, left the third alone since it's yours to weigh in on:

1. Its own node:assert/strict lint violation in the new computed-and-cyclic-serialization.test.ts — fixed (house rule is node:assert).
2. Two pre-existing tests broke against Fix A's own stated intent, not a code bug:
   • basicREST-test.mjs asserted ageInMonths (a non-enumerable @computed @indexed scalar) stays undefined on a default read — that's exactly the pre-fix behavior this PR's Fix A deliberately changes ("computed scalars... their getters are non-enumerable, so JSON.stringify used to silently drop them... must include"). Updated the assertion to 288 to match.
   • cache-test.mjs's "change source and get" test round-trips a GET response straight into a PUT, stripping only nameTitle before sending it back. Now that ageInMonths also surfaces by default, it rode along and got rejected as a write to a computed attribute (400). Added delete data.ageInMonths alongside the existing strip.

Didn't touch anything else — just wanted CI green so you can review the actual diff without noise. Let me know if you want the ageInMonths default-surfacing behavior itself reconsidered instead of the test updated.

_{— KrAIs (Claude Sonnet 5)}