core: cloneAsOverride keeps its input's deep-readonly type, so a Tenant/User override clone does not type-check as mutable

[os-support-ai]

Filed unassigned from the implementation of #5160. Not fixed there — that card only changes documentation, never the export surface, and this is the export surface.

What was measured

packages/core/src/utils/freeze-schema.ts declares:

export declare function defineSystemView< T extends object >(schema: T): SystemView< T >;
export declare function cloneAsOverride< T >(view: T): T;

SystemView< T > is DeepReadonly< T > & { readonly [SYSTEM_VIEW_MARKER]?: true }. Because cloneAsOverride returns T unchanged, cloning a System View returns something still typed deep-readonly, even though the implementation produces a plain mutable object (structuredClone, or a JSON round-trip fallback) and deliberately drops the marker symbol.

So the documented override flow does not type-check. Measured against the built packages/core/dist/index.d.ts with the #5138 snippet gate, over packages/core/README.md:

packages/core/README.md:121:15 TS2339: Property 'push' does not exist on type 'readonly { readonly name: string; }[]'.

That line in the README is:

const draft = cloneAsOverride(userListView)
draft.columns.push({ name: 'name' }) // ✅ allowed

The comment is correct about runtime and wrong about the type. The neighbouring line one block up is the intended opposite and is correctly rejected:

packages/core/README.md:116:22 TS2339: Property 'push' does not exist on type 'readonly { readonly name: string; }[]'.

...which is the userListView.columns.push(...) // ❌ TypeError (strict mode) demonstration — that one is correct documentation, and freeze-schema.ts's own JSDoc shows the same line for the same purpose.

Why this was invisible until now

packages/core/README.md imported defineView, a name core does not export (it was renamed to defineSystemView in objectstack#4115). Under the missing import, userListView was an error type, so neither .push line was ever checked. Fixing the import in #5160 is what surfaced both. The diagnostic count on that document went up, not down — the two TS2339s are pre-existing and were masked, not introduced.

Whose defect this is

The ⛔ boundary in #5160 was "documentation changes, never the export surface", so the README was left alone and this was filed instead. There is a real decision here rather than an obvious patch:

• A. cloneAsOverride< T >(view: T): Mutable< T > — strip DeepReadonly on the way out, so the returned clone types the way it behaves. Needs a Mutable/DeepMutable inverse of the existing DeepReadonly, and a consumer sweep.
• B. Leave the signature and change the README to annotate or cast the draft. Teaches a cast around a type that is simply wrong about its own value — a lenient read at the consumer, which AGENTS.md #0.1 rules out.
• C. Leave both and declare the README block a fragment. Hides a real signature defect behind the gate's fragment marker.

A looks right; A is a contract change and wants a maintainer ruling.

Related

• docs: five published READMEs import symbols their packages do not export — 15 TS2305, measured against the built dist #5160 — the card that surfaced it; defineView → defineSystemView is fixed there, this is not
• finding: no gate reads a doc snippet's schema KEYS against the spec — #4823's deferred "second dimension", closed unbuilt #5138 — the snippet compile gate that measures it

[os-support-ai]

Triage: escalating to the decision inbox — option A changes an exported signature on a published package (public-contract change → human floor), and the filer explicitly asked for a ruling. Typed Bug (the declared type contradicts the implemented behaviour).

Four-prism:

• Platform coherence — cloneAsOverride produces a mutable clone but keeps the deep-readonly type; the declaration is simply wrong about its value. A makes type = behaviour.
• Measured business pull — the documented override flow does not type-check (README draft.columns.push → TS2339, measured by the finding: no gate reads a doc snippet's schema KEYS against the spec — #4823's deferred "second dimension", closed unbuilt #5138 gate).
• AI-agent error-resistance — B teaches a cast (the lenient-consumer pattern AGENTS.md #0.1 rules out); C hides a real signature defect behind a fragment marker; A is the only option where the compiler tells the truth.
• Startup scope discipline — A is contained: one signature, a Mutable/DeepMutable inverse of the existing DeepReadonly, and the consumer sweep the card names; the return type relaxes toward what the runtime already does, so existing callers keep compiling.

Recommendation: A (cloneAsOverride<T>(view: T): Mutable<T>), with the consumer sweep.

---

Generated by Claude Code

[os-elon]

Maintainer ruling — recorded by the maintainer-directed PM session (session_01KspKtTajJmy3J37UhH8tcH, 2026-08-19). The 27-card objectui decision-inbox review (per-card four-axis analysis) was presented to the maintainer in that session's chat; the maintainer's verbatim reply: 「全部接受」. Adopted ruling, restated in full:

Ruling: Option A — cloneAsOverride returns Mutable<T>

• Change the signature so the return type tells the truth about the value: the implementation produces a plain mutable clone, so the type stops claiming deep-readonly. Requires a Mutable/DeepMutable inverse of DeepReadonly and a consumer sweep; the return type relaxes toward runtime behaviour, so existing callers keep compiling.
• The documented override flow (packages/core/README.md:121, draft.columns.push(...)) must type-check after the change — that is the acceptance criterion, verified by the finding: no gate reads a doc snippet's schema KEYS against the spec — #4823's deferred "second dimension", closed unbuilt #5138 snippet gate.
• B (teach a cast in the README) is rejected — lenient-consumer pattern AGENTS.md #0.1 rules out; C (declare the block a fragment) is rejected — it hides a real signature defect behind the fragment marker.

State: needs-user-decision → pm:queue.

---

Generated by Claude Code