feat(spec): App as the consumer-facing unit (ADR-0019) (#1406)

* docs(adr): ADR-0019 App as the consumer-facing unit (Package ≡ App)

Establish the App as the single consumer-facing noun: download = open =
uninstall, one identity throughout. Internal composition (plugins,
modules, drivers) becomes invisible bundle detail, like frameworks inside
a .app. Remove the suite-contains-apps container; HotCRM folds into one
App. Builds on ADR-0003.

* docs(adr): ADR-0019 v2 — merge metadata/code plane split & capability contract

Merge Axis B into ADR-0019: packages are two categories (metadata, hot-
loaded; code, compiled into the server build), mapped to two runtime
planes joined by a capability-by-reference contract. Add D5-D7 (two
planes; consumer App must be pure metadata; requires/provides contract).
Relax D4: an App owns a SET of namespaces (uninstall removes the set),
so suites fold without object renames. Record honestly that the
capability contract is mostly unbuilt today (closed CAPABILITY_PROVIDERS
table + inert provides/requires schema) and surface the risks as
Consequences and Open questions.

* feat(spec): ADR-0019 P2 — manifest two-tier + consumer-App rules (warn-only)

Add CONSUMER_INSTALLABLE_TYPES + isConsumerInstallable (D2 tier split),
and a consumer-app-rules module with validateConsumerAppPurity (D6) and
validateRequiresShape (D7). Wire both into defineStack as non-blocking
warnings so existing code-bearing apps still build. Add tests + a P2
landing-plan doc. No runtime/registry changes (capability registry +
install gate remain P4).

* refactor(spec): narrow ADR-0019 to 'App as consumer unit'; revert plane/purity scope

Per design review, narrow the scheme to its one cheap, certain part — the
consumer surface is one App — and revert the metadata/code plane, D6 purity,
and D7 capability-contract apparatus (premises did not hold: consumer apps
legitimately carry code-bearing metadata like L2 sandboxed-JS hooks, and
auto-review was dropped as a requirement).

Lands:
- isConsumerInstallable(type) + CONSUMER_INSTALLABLE_TYPES (single source of truth)
- MarketplaceListingSchema.packageType constrained to consumer-installable types,
  so a non-App consumer listing cannot be represented (guarantee in the contract)

Reverts: consumer-app-rules.{ts,test.ts}, the defineStack warn-only wiring, the
P2 plan doc. ADR-0019 rewritten to v3 (decision = D1-D4; the larger scheme moved
to an explicit, gated 'Out of scope' section).

* feat(spec): enforce one App per package in defineStack (ADR-0019 D1/D3)

A package with manifest.type === 'app' must define exactly one app. Zero is
rejected (an app package with no app surface); more than one is the banned
'suite contains apps' shape — fold into one app with multiple tabs, or split
into separate packages. Non-app package types are unconstrained. Mirrors the
existing validateNamespacePrefix pattern. Existing examples already define
exactly one app, so this is non-breaking.

* fix(spec): relax one-App rule to 'at most one'; restore green suite

The previous commit hard-required exactly one app for type:app packages,
which broke 31 existing spec fixtures that use type:app with zero apps to
test unrelated behavior. The banned case per ADR-0019 D3 is *multiple* apps
(the suite shape), not zero. Relax validateSingleApp to reject >1 only;
allow 0. Add tests. Full spec suite green (6628), tsc clean, compose-stacks
+ app-crm smoke green.

* test(spec): cover at-most-one-App rule in defineStack (ADR-0019)

Adds the validateSingleApp tests that failed to land in the prior commit:
one app ok, zero apps ok, >1 app throws, non-app types unconstrained.

* fix(spec): make at-most-one-App tests use cross-ref-valid apps

The reject-case test used name+label-only apps, which trip the cross-
reference landing check (runs before the single-app rule) and threw the
wrong error. Give each app navigation to a defined object so the suite
fixture reaches validateSingleApp. Full spec suite green (6628), tsc clean.

* fix(spec): use valid 2-char app names in non-app-type test fixture

Final fix for the at-most-one-App test suite: the driver fixture used
single-char app names ('a'/'b') which fail the SnakeCaseIdentifier
min-2-char rule and threw the wrong error. Use 'app_a'/'app_b'. Full spec
suite green (6624 passed, 0 failed), tsc clean.

* docs: align package-registry + marketplace-publishing to ADR-0019

Update the two docs that still described the old 'suite contains apps'
model:
- package-registry.zod.ts doc comment: App is the one consumer unit; a
  consumer package defines at most one app; internal contributions are
  invisible bundle parts.
- marketplace-publishing.md §1-2 + §6: taxonomy rewritten around the App;
  HotCRM reference reframed as one App with internal plugins; §6 replaced
  with the two valid shapes (one App bundling plugins, or independent Apps)
  and an explicit 'no suite' note.

* docs: finish ADR-0019 alignment in marketplace-publishing + package-registry

Complete the partial doc update: package-registry.zod.ts header comment and
marketplace-publishing.md sections 2.1/2.2/6 + summary now describe the App as
the one consumer unit (at most one app per package; internal contributions
invisible; no suite-contains-apps). Removes the remaining old 'suite' wording.

* docs(spec): fix package-registry header to ADR-0019 (App is the consumer unit)

The earlier 'docs: align ...' commit message claimed this file was updated,
but the edit had silently failed — the header still described the old
'package may contain ... multiple apps (suite of applications)' model. Replace
it with the ADR-0019 model: App is the one consumer-facing unit, at most one
app per consumer package, internal contributions invisible. No 'suite'.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/consumer-app-two-tier.md

@@ -0,0 +1,21 @@
+---
+"@objectstack/spec": minor
+---
+
+ADR-0019 — App as the consumer-facing unit. The consumer Marketplace surfaces
+exactly one user-visible noun, the App.
+
+- Adds `CONSUMER_INSTALLABLE_TYPES` and `isConsumerInstallable(type)` (the single
+  source of truth for "what a consumer can install").
+- Constrains `MarketplaceListingSchema.packageType` to `CONSUMER_INSTALLABLE_TYPES`
+  (default `app`) so a non-App (driver/server/plugin/…) listing cannot be
+  represented — the "consumers see only Apps" guarantee is enforced in the data
+  contract, not a forgettable query filter.
+- `defineStack()` now enforces **at most one App per package**: a package with
+  `manifest.type === 'app'` may not define more than one app — the banned "suite
+  contains apps" shape throws with a clear fix (fold into one app with multiple
+  tabs, or split into separate packages). Zero apps is allowed; non-`app`
+  package types are unconstrained. Non-breaking for existing stacks.
+
+The package `type` enum is unchanged; the additions are non-breaking. No
+runtime/registry/execution changes.

docs/adr/0019-app-as-consumer-unit.md

@@ -0,0 +1,179 @@
+# ADR-0019: App as the Consumer-Facing Unit
+
+**Status**: Proposed (v3 — narrowed to the consumer-surface decision)
+**Date**: 2026-05-31
+**Deciders**: ObjectStack Protocol Architects
+**Builds on**: ADR-0003 (Package as First-Class Citizen), ADR-0006 (Three-Layer Tenancy), ADR-0016 (Studio Package Authoring & Publish)
+**Consumers**: `@objectstack/spec/kernel` (`plugin.zod.ts`), `@objectstack/spec/cloud` (`marketplace.zod.ts`), the Console `marketplace` UI, the Studio publish flow, `docs/design/marketplace-publishing.md`
+
+> **Revision history**
+> - **v1/v2** explored a much larger scheme: a metadata/code *plane* split,
+>   a "consumer App must be pure metadata" mandate (D6), a capability-by-
+>   reference contract (D7), and auto-reviewed Marketplace trust lanes.
+> - **v3 deliberately narrows this ADR to its one cheap, certain, high-value
+>   part: the consumer surface.** The larger scheme was dropped from scope
+>   because the design review found its premises did not hold (consumer apps
+>   legitimately contain code — e.g. L2 sandboxed-JS hooks — so "pure metadata"
+>   is not real; and auto-review was dropped as a requirement). The remaining
+>   hard problems (capability registry/versioning, sandbox hardening, shared
+>   data model, data migration) are recorded in §Out of scope as a *separate,
+>   gated* bet, not part of this decision.
+
+---
+
+## Context
+
+ADR-0003 made the **package** a first-class versioned artifact, but said
+nothing about the **consumer mental model** — what a non-developer sees,
+installs, opens, and removes.
+
+Today that surface is muddy. `manifest.zod.ts` exposes a **Package** that can be
+any of ten `type`s and may contain *0, 1, or N apps* (a "suite").
+`package-registry.zod.ts` codifies it:
+
+> **Package**: the unit of installation. **App**: a UI navigation shell *inside*
+> a package. A package may contain zero apps (driver), one app (typical), or
+> multiple apps (suite).
+
+The reference implementation **HotCRM** is the worst case: one `type: app`
+package aggregating 13 sub-plugins, each with its own namespace. A consumer
+cannot tell what they installed, what "opening" means, or what uninstall
+removes. This is the Microsoft-Office "suite contains applications" model — and
+its inherent confusion.
+
+The Apple model is the opposite and the target: **there is no user-visible
+container above the app**. The thing you download *is* the one you open *is* the
+one you remove — one noun. Even iWork ships as three separate apps, not a suite.
+
+---
+
+## Decision
+
+### D1 — The App is the only consumer-facing unit
+
+The thing a user downloads, opens, and uninstalls is exactly one **App**. The
+word "package" is retained as an internal / developer / control-plane term (the
+ADR-0003 artifact) but is **never surfaced to consumers**. A Marketplace
+**listing is an App listing**.
+
+### D2 — Only `type: app` is consumer-installable; everything else is invisible
+
+The package `type` enum is unchanged, but a semantic split is layered over it:
+
+| Tier | Types | Consumer-installable? | In consumer Marketplace? |
+|---|---|---|---|
+| **Consumer unit** | `app` | Yes | Yes (App listing) |
+| **Internal contribution** | `plugin`, `driver`, `server`, `ui`, `theme`, `agent`, `objectql`, `module`, `adapter` | No | No |
+
+Internal contributions are the "frameworks inside the `.app` bundle": they ship
+inside an App or are operator-provisioned, and are never independently browsed
+or installed by a consumer. The consumer Marketplace filters to `type: app` via
+`isConsumerInstallable(type)` (`packages/spec/src/kernel/plugin.zod.ts`).
+
+### D3 — Suites fold into a single App (no aggregator above App)
+
+The "package contains N apps (suite)" shape is removed from the consumer model.
+A vertical solution that today aggregates many plugins MUST resolve to **one
+App** whose internal plugins are invisible. A developer who genuinely wants
+independent products ships them as **independent Apps** (the iWork route), never
+as a wrapper that surfaces N apps.
+
+### D4 — An App owns a set of namespaces; uninstall removes the set
+
+An App declares and owns a set of namespaces; uninstall is atomic over that set.
+(The runtime already supports this: `objectql/src/registry.ts` keys namespaces
+as `Map<namespace, Set<packageId>>`.) Folding a suite like HotCRM therefore
+needs no object rename — the single App simply owns the namespaces its former
+sub-plugins used.
+
+---
+
+## Scope of this ADR (what lands)
+
+- **Decision**: D1–D4 above — the consumer surface is one App.
+- **Code (landed)**:
+  - `CONSUMER_INSTALLABLE_TYPES` + `isConsumerInstallable(type)` in
+    `plugin.zod.ts` — the single source of truth (additive, non-breaking).
+  - `MarketplaceListingSchema.packageType` constrained to
+    `CONSUMER_INSTALLABLE_TYPES` (`marketplace.zod.ts`) — the data contract now
+    **cannot represent a non-App consumer listing**, so the "consumers see only
+    Apps" guarantee is enforced at the schema level rather than left to a query
+    filter that could be forgotten.
+- **Follow-up (thin, surfaces outside this package)**: have the Console
+  `marketplace` UI / cloud catalog populate `packageType` from the manifest
+  (the catalog is cloud-served and proxied verbatim by
+  `runtime/cloud/marketplace-proxy-plugin.ts`), and fold HotCRM to a single App
+  (D3/D4). Both consume the same `isConsumerInstallable` predicate.
+
+Nothing in this ADR changes the runtime, the registry, or how packages execute.
+
+---
+
+## Out of scope (explored, deferred — a separate gated bet)
+
+The following were explored in v1/v2 and **deliberately removed** from this
+decision. They form a distinct, multi-quarter platform investment that should
+get its own ADR and an explicit go/no-go — they are **not** prerequisites for
+D1–D4:
+
+- **Metadata/code runtime planes** (hot-loadable sandboxed source vs npm code
+  baked into the server image). Useful as a *descriptive* mental model; not a
+  decision here.
+- **"Consumer App must be pure metadata" (old D6).** Dropped — apps legitimately
+  carry code-bearing metadata such as L2 sandboxed-JS hooks
+  (`data/hook.zod.ts`: `body.language: 'js'` with declared `capabilities`).
+  "Pure metadata" is not a real boundary.
+- **Capability-by-reference contract + open capability registry + install gate
+  (old D7).** The real long-term hard problem (versioning / semantic drift); the
+  current mechanism is the closed `CAPABILITY_PROVIDERS` table in
+  `runtime/src/cloud/capability-loader.ts` plus an inert `provides/requires`
+  schema.
+- **Auto-reviewed Marketplace trust lanes.** Dropped as a requirement.
+- **The runtime safety boundary** for self-serve code-bearing apps: the **L2
+  hook sandbox + capability/permission enforcer**
+  (`core/src/security/plugin-permission-enforcer.ts`). If a self-serve,
+  code-bearing Marketplace is ever pursued, *this* — not review, not a purity
+  rule — is the load-bearing wall, and its hardness must be proven first.
+- **Shared/published data model + inter-App dependencies** (cross-app data
+  sharing without a "suite").
+- **Metadata-with-data migration framework** (backfill, destructive-change
+  confirmation, reversible uninstall of object data).
+
+---
+
+## Consequences
+
+**Positive**
+- One noun for consumers: install = open = uninstall, the model everyone already
+  knows from their phone. Cheap, low-risk, independently shippable.
+- The confusing "package / suite" abstraction disappears from the consumer view.
+- No runtime, registry, or execution changes — the blast radius of this ADR is
+  the Marketplace/Console listing surface plus one additive predicate.
+
+**Negative / costs**
+- HotCRM and any existing suite-style packages must fold to a single App (D3/D4).
+- "Publish a standalone consumer plugin" is no longer a consumer path; plugins
+  ship inside an App or are operator-provisioned.
+
+---
+
+## Alternatives considered
+
+1. **Keep the suite model, improve the install UX.** Rejected: a 1-to-N noun is
+   a structural problem; wording cannot fix it.
+2. **Expose both "App" and "Suite" as consumer units.** Rejected: reintroduces
+   the container-above-app this ADR removes.
+3. **The full v1/v2 scheme (planes + purity + capability contract + trust
+   lanes).** Deferred — see §Out of scope. Its premises did not hold and its
+   hard parts are a separate, gated investment.
+
+---
+
+## References
+
+- ADR-0003 — Package as First-Class Citizen with Versioned Releases
+- ADR-0006 — Three-Layer Tenancy (Organization, Project, Environment)
+- ADR-0016 — Studio Package Authoring & Publish
+- `packages/spec/src/kernel/plugin.zod.ts` (`isConsumerInstallable`)
+- `packages/spec/src/cloud/marketplace.zod.ts`
+- `docs/design/marketplace-publishing.md`

docs/design/marketplace-publishing.md

@@ -2,6 +2,9 @@
 
 > **Author:** ObjectStack Core Team  
 > **Created:** 2026-02-17  
+> **Updated:** 2026-05-31 — §1–2 and §6 aligned to ADR-0019 (App as the
+> consumer-facing unit; no "suite contains apps"; consumer Marketplace lists
+> only `type: app`).  
 > **Status:** Design Specification  
 > **Target Version:** v3.2 – v4.0
 
@@ -35,33 +38,44 @@ The marketplace protocol consists of three primary schema files:
 
 ### Reference Implementation
 
-**HotCRM** (`objectstack-ai/hotcrm`) demonstrates a real-world metadata-only application with:
-- Root `objectstack.config.ts` with `type: 'app'` aggregating 13 plugins
-- 13 sub-plugins (crm, finance, marketing, products, support, hr, analytics, integration, community, healthcare, real-estate, education, financial-services)
-- 30+ metadata types per plugin
+**HotCRM** (`objectstack-ai/hotcrm`) demonstrates a real-world application. Per
+ADR-0019, it is being refolded into a **single consumer App** (download = open =
+uninstall) whose internal plugins are invisible "frameworks inside the bundle":
+- Root `objectstack.config.ts` with `type: 'app'` — one consumer-facing App
+- The former sub-plugins (crm, finance, marketing, …) are internal
+  contributions bundled inside the App, not separately listed or installed
+- The App owns the set of namespaces those contributions use; uninstall is
+  atomic over that set
 
 ---
 
 ## 2. Architecture Overview
 
-### 2.1 Package Taxonomy
+### 2.1 Package Taxonomy (ADR-0019)
 
-The ObjectStack ecosystem uses a clear hierarchy:
+The ObjectStack ecosystem exposes **one consumer-facing noun: the App.**
 
 ```
-Package (ManifestSchema)
-├── Type: app | plugin | driver | server | ui | theme | agent | module
-├── Namespace: Scoped identifier (e.g., "crm" → crm__account, crm__deal)
-└── May Contain: Zero apps | One app | Multiple apps
+App  ← the only consumer unit (download = open = uninstall)
+├── Type: app   (the only consumer-installable type; see isConsumerInstallable)
+├── Namespace(s): the App owns a set; uninstall is atomic over the set
+├── Apps:   at most one app surface per package (one app, many tabs — no suite)
+└── Internal contributions (invisible): plugin | driver | server | ui | theme | agent | module
+       — "frameworks inside the .app bundle": bundled or operator-provisioned,
+         never independently listed or installed by a consumer
 ```
 
-### 2.2 Package vs App vs Plugin
+### 2.2 App vs Package vs internal contribution
 
-From `packages/spec/src/kernel/package-registry.zod.ts`:
+From `packages/spec/src/kernel/package-registry.zod.ts` (ADR-0019):
 
-> **Package**: The unit of installation — a deployable artifact containing metadata  
-> **App**: A UI navigation shell defined inside a package  
-> A package may contain zero apps (driver), one app (typical), or multiple apps (suite)
+> **App**: the one consumer-facing unit — what a tenant downloads, opens, and
+> uninstalls. Only `type: app` is consumer-installable, and a consumer package
+> defines **at most one app** (no "suite contains apps").  
+> **Package**: the internal / control-plane artifact term; never surfaced to
+> consumers as a separate noun.  
+> **Internal contributions** (plugin/driver/server/…): ship inside an App or are
+> operator-provisioned; a consumer never installs them directly.
 
 ### 2.3 Namespace Scoping
 
@@ -353,56 +367,51 @@ Steps:
 
 ---
 
-## 6. Publishing Strategies for Multi-Plugin Applications
+## 6. Composing a Multi-Plugin Application (ADR-0019)
 
-### 6.1 HotCRM Architecture
+The consumer model has **one user-visible noun — the App — and no "suite
+contains apps" aggregator**. A solution built from many internal plugins has
+exactly two valid shapes; both ship as *one App* (or several independent Apps)
+to the consumer, never as a wrapper that surfaces N apps.
 
-13 plugins: crm, finance, marketing, products, support, hr, analytics, integration, community, healthcare, real-estate, education, financial-services
+### 6.1 Shape A — One App, internal plugins bundled (recommended for HotCRM)
 
-### 6.2 Strategy A: Suite Mode
+Compose all internal plugins into a single `type: 'app'` package. The plugins
+are "frameworks inside the .app bundle" — invisible to the consumer. The App
+defines **at most one app surface** (one app with multiple tabs) and owns the
+set of namespaces its plugins use.
 
-**Approach:** Bundle all 13 plugins in one package
-
-**Pros:** Simple install, guaranteed compatibility, single version  
-**Cons:** Large size, no modularity  
-**Use Case:** Enterprise bundle
-
-### 6.3 Strategy B: Individual Listings
-
-**Approach:** Each plugin published separately
-
-**Pros:** Modular, pay-per-module, independent versioning  
-**Cons:** Complex dependencies, version matrix  
-**Use Case:** Marketplace à la carte
-
-### 6.4 Strategy C: Hybrid (Recommended)
-
-**Approach:** Core bundle + industry extensions
-
-**Base Package:** crm + finance + products + support + hr + analytics + integration
+```typescript
+// objectstack.config.ts
+export default defineStack({
+  manifest: { id: 'com.hotcrm', type: 'app', namespace: 'hotcrm', version: '2.0.0' },
+  plugins: [crmPlugin, financePlugin, marketingPlugin, /* … */], // invisible internals
+  apps: [hotcrmApp], // exactly one consumer app surface (multiple tabs), not a suite
+});
+```
 
-**Extensions (separate):**
-- healthcare
-- real-estate
-- education
-- financial-services
+**Pros:** one listing, one install, atomic versioning and uninstall, one noun
+for the consumer.
 
-**Pros:** Balanced, core always available, optional verticals  
-**Use Case:** Commercial SaaS with verticals
+### 6.2 Shape B — Several independent Apps (the iWork split)
 
-### 6.5 Dependency Declaration
+If verticals are genuinely separate products, ship each as its **own App
+package** — its own listing, install, namespace, and lifecycle (like Pages /
+Numbers / Keynote). This is *not* a suite: there is no wrapper above them.
 
-```typescript
-export default defineStack({
-  id: 'com.hotcrm.healthcare',
-  dependencies: {
-    'com.hotcrm.base': '^1.0.0',
-    'com.hotcrm.analytics': '^1.1.0'
-  }
-});
+```bash
+os publish   # com.hotcrm.crm     (type: app)
+os publish   # com.hotcrm.finance (type: app)
 ```
 
-Kernel resolves graph, installs deps first, validates versions, rejects cycles.
+**Pros:** granular adoption, independent versioning.
+**Cons:** verticals do not share one install; cross-app data sharing is a
+separate concern (see ADR-0019 §Out of scope).
+
+> **Not allowed:** a "meta-package" / suite whose only job is to surface N apps
+> to the consumer — the Office "suite contains applications" model ADR-0019
+> removes. `defineStack` enforces *at most one app* per `type: app` package, and
+> the consumer Marketplace lists only `type: app`.
 
 ---
 
@@ -591,7 +600,7 @@ This comprehensive design document establishes the **Marketplace Protocol** for
 2. **Publishing**: 6-step flow (develop → validate → build → submit → review → publish)
 3. **Installation**: 4 channels (CLI, SDK, API, UI) with 30+ metadata type registration
 4. **Lifecycle**: State machine for install/enable/disable/upgrade/uninstall
-5. **Strategies**: 3 approaches for multi-plugin apps (Suite, Individual, Hybrid)
+5. **Composition** (ADR-0019): one App (internal plugins bundled) or several independent Apps — never a suite
 6. **Security**: 5-level verification, signing, automated scanning, permission review
 7. **Pricing**: 6 models (free to enterprise) with license validation
 8. **Roadmap**: 5 phases across 4 quarters