Epic: package-first authoring (ADR-0070) — bases as the authoring & delete unit

[os-zhuang]

ADR: framework#2277 (ADR-0070, Accepted). This card tracks the cross-repo rollout.

Status (2026-06-27): functionally complete. All six decisions (D1–D6) are implemented and merged across framework / ../objectui / ../cloud, and ADR-0070 is Accepted with an end-to-end live dogfood. The full lifecycle is now also covered by an automated gate (framework#2358). One deliberately-deferred tail remains, tracked as #2359 (retire the "Local / Custom" stopgap scope once envs are orphan-free). See the status comment below for the PR-by-PR map.

Problem (from a business-user Studio dogfood pass)

Authored metadata can end up orphaned (package_id = null) with no container to delete/export — "a pile of loose metadata, how do I clean it up?". Root cause: no package-first contract. Stopgaps shipped: framework#2252 (coerce-to-null), objectui#1946 (Local scope). We adopt the Airtable base model: create/select a writable package (base) first; author into it; manage/delete/export by base.

Rollout checklist

• kernel (D1/D2) — isWritablePackage predicate + reject runtime creates with no writable target (code: 'writable_package_required'); evolved fix(objectql): don't stamp runtime-authored metadata into a loaded code package #2252 coerce-to-null → reject. @objectstack/objectql protocol.saveMetaItem. ✅ framework#2285
• Studio UI (D3) — create entry points prompt/redirect to a writable base; selector defaults to a writable base, never null/code-pkg; new items bound to the active base. ../objectui. ✅ objectui#1970
• AI authoring (D3) — ../cloud service-ai-studio: dropped auto-com.workspace fallback; auto-creates an intentional named base via installPackage; requires package context. ✅ cloud#479 / chore(deps)(deps): bump commander from 11.1.0 to 14.0.3 #481 / tests chore(deps)(deps): bump react and @types/react #480 (+ follow-ups Add auth plugin package with route scaffolding and service registration #577 / Fix startup message to show correct API endpoint #588 / Align authentication endpoints with better-auth protocol #590 "Edit with AI")
• Package = lifecycle unit (D4) — delete-cascade + export (shipped) and duplicatePackage (re-namespace + reference rewrite). UI: Duplicate / structure-only delete. ✅ framework#2299, objectui#1983
• Migration (D5) — reassignOrphanedMetadata + POST /packages/:id/adopt-orphans (+ "Adopt loose items" UI) bulk-rebind legacy null rows. ✅ framework#2301, objectui#1983. ◐ tail: removing the chore(spec): prune 7 dead field governance/compliance props (dead-surface plan) #1946 "Local / Custom" scope is gated on envs being orphan-free → tracked in ADR-0070 D5 tail: retire the "Local / Custom" stopgap scope from the Studio selector (once envs are orphan-free) #2359. (fix(objectql): don't stamp runtime-authored metadata into a loaded code package #2252 coerce-to-null already replaced by the D1 reject.)
• Single-tenant default (D6) — default to a writable base, never a null "org/local" scope. ✅ framing in ADR + objectui#1983; cloud#588 (each build → fresh base).
• Dogfood gate — @objectstack/dogfood coverage: create→bind→publish→editable→discoverable→delete-cascade + adopt-orphans + duplicate, against the real booted stack. ✅ framework#2303 (D1/D2) + framework#2358 (full D3/D4/D5 lifecycle); cloud#594 / [WIP] Release patch version for updates #598 (quantified build-quality evals).

Open questions (resolved)

1. Auto-provision a base on first authoring → resolved: a prompted/named one-click base (cloud auto-creates a named base; no silent com.workspace).
2. allowOrgOverride in single-tenant → keep overlay for surgical tweaks (design note; non-blocking).
3. Delete-cascade also delete records? → resolved: deletePackage({ keepData }) + a "structure-only delete" UI option (objectui#1983).
4. Base naming vs stable id (app.<slug>) → surface a name, keep the id stable (design note).

Repos: framework (kernel, ADR, dogfood gate), ../objectui (Studio), ../cloud (service-ai-studio). Remaining tail: #2359.

[xuyushun441-sys]

Completion assessment + what just shipped

This epic is functionally complete — every decision (D1–D6) is implemented, merged across all three repos, and live-verified; ADR-0070 is Accepted. The checklist boxes above were stale relative to the merged work, so I've ticked them with the PR-by-PR map. Two loose ends were identified; one is now closed, one is intentionally deferred.

PR map

Decision	Status	Evidence
D1/D2 kernel reject	✅	framework#2285 (isWritablePackage, writable_package_required 422)
D3 Studio create-flow	✅	objectui#1970
D3 AI authoring	✅	cloud#479 / #481 / #480 (+ #577 / #588 / #590)
D4 lifecycle unit	✅	framework#2299 (duplicate), objectui#1983 (Duplicate / structure-only delete)
D5 migration	✅ tooling / ◐ tail	framework#2301 + objectui#1983; stopgap-scope removal → #2359
D6 single-tenant default	✅	ADR + objectui#1983 + cloud#588
Dogfood gate	✅	framework#2303 (D1/D2) + framework#2358 (full lifecycle) + cloud#594 / #598

Just shipped — framework#2358 (automated the dogfood gate)

The gate previously only proved the D1/D2 backstop; the rest of the chain was hand-verified. framework#2358 promotes it to an automated proof against the real booted stack: create → bind → publish → editable → discoverable → delete-cascade, plus reassignOrphanedMetadata (D5) and duplicatePackage (D4). 5 passed (5) locally.

Remaining tail (deferred by design) → #2359

Removing the #1946 "Local / Custom" selector scope is the last step of D5, but ADR-0070 gates it on environments being orphan-free (the adopt-orphans tooling that makes it safe is already merged). Split into #2359 so this epic can close once #2358 merges.

Recommendation

Close this epic when framework#2358 merges; track the orphan-free stopgap removal under #2359.

[os-zhuang]

Update — the last D5 tail is now implemented (PR up, CI green)

Since the system is pre-launch, the "migrate envs to orphan-free first" gate on the stopgap removal doesn't apply, so it was removed outright rather than deferred:

• objectui#2025 — removes the "Local / Custom (this env)" package-selector scope (the package_id = null / sys_metadata orphan bucket from chore(spec): prune 7 dead field governance/compliance props (dead-surface plan) #1946). buildPackageScopeOptions now returns writable bases only; isLocalScope/LOCAL_PACKAGE_ID/writableBaseOptions and the create-flow/list/home special-casing are gone. Read-side sys_metadata legacy-provenance handling is kept (ADR-0070 D5). CI green (Test, Build & E2E, Changeset, Docs; 931 unit tests). Tracked as ADR-0070 D5 tail: retire the "Local / Custom" stopgap scope from the Studio selector (once envs are orphan-free) #2359.

With this, all of D1–D6 (including the D5 stopgap removal) are implemented, and the dogfood gate is automated (framework#2358, also green). Once framework#2358 and objectui#2025 merge, this epic and #2359 can both close — there is no remaining package-first work.