docs(adr): ADR-0069 — package-first authoring (Airtable base model)

[os-zhuang]

Status: Proposed — drafted from a business-user Studio dogfood pass; opening for team decision.

What

ADR for the Airtable-style package-first model: every runtime-authored metadata item must live in a writable package (base); no orphans. Code/installed packages are read-only; the package is the delete / export / duplicate unit (the answer to "a pile of loose metadata — how do I delete it?").

Why now

A dogfood pass surfaced a family of defects with one root cause — no package-first contract:

• fix(objectql): don't stamp runtime-authored metadata into a loaded code package #2252 (read-only after publish): code-package context stamped new objects read-only → stopgap coerces to package_id = null.
• chore(spec): prune 7 dead field governance/compliance props (dead-surface plan) #1946 (orphan pile): the null bucket has no delete container and is filtered out of package-scoped lists.
• ../cloud service-ai-studio can still silently default into a catch-all com.workspace.

The ADR unifies the contract across kernel (saveMetaItem), Studio UI, and ../cloud AI authoring, and retires #2252 / #1946 as transitional.

Decisions

• D1 no orphan authored metadata (writable package_id required; kernel rejects with writable_package_required)
• D2 two package kinds — code/installed = read-only, writable bases = the only authoring target
• D3 create-flow contract enforced on all three surfaces (pick/create a base first; no silent default)
• D4 package = lifecycle unit (delete-cascade / export / snapshot / duplicate)
• D5 retire the fix(objectql): don't stamp runtime-authored metadata into a loaded code package #2252/chore(spec): prune 7 dead field governance/compliance props (dead-surface plan) #1946 stopgaps via a migration affordance
• D6 single-tenant framing; reject "org/local default" (it reproduces the orphan pile)

Tracking epic + rollout: see the package-first card.

🤖 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 24, 2026 9:51am