feat(spec)!: drop the @objectstack/spec/cloud subpath — control-plane contracts leave, the package format moves to @objectstack/spec/marketplace

.changeset/spec-cloud-subpath-retired.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/spec": minor
+"@objectstack/cli": patch
+"@objectstack/metadata": patch
+---
+
+feat(spec)!: the `@objectstack/spec/cloud` subpath is removed — the cloud control plane's contracts leave the open-source spec, and the package & marketplace format moves to `@objectstack/spec/marketplace` (#16325)
+
+<!-- adr-0087: registered cloud-subpath-retired -->
+
+**BREAKING** — a published subpath export of `@objectstack/spec` is deleted, with no
+alias and no deprecation window (maintainer, 2026-08-27, verbatim: 「项目在创业阶段，
+用户也很少，短期不考虑渐进。」). Shipped as `minor` under the repo's launch-window
+convention, in which `major` is refused by `check-changeset-no-major` and breaking-ness
+is carried by this banner plus the ADR-0087 disposition; the hand-migration prescription
+is registered under protocol major 18 as `cloud-subpath-retired`.
+
+## What moved, and why
+
+Maintainer direction (2026-09-06, verbatim): 「我一直觉得 cloud 的协议应该放在云端，没必要开源」,
+ruled option B "cut by owner" on #16325 (director batch #62, 2026-09-07, 「同意」).
+`packages/spec/src/cloud/` held two families with different owners:
+
+- **The cloud control plane's own contracts** — `environment.zod`, `environment-package.zod`,
+  `tenant.zod`, `developer-portal.zod`, `marketplace-admin.zod`, `app-store.zod` (62 JSON-Schema
+  defs, 2087 lines). Their producer and every consumer live in the closed cloud repo; the
+  open-source tree read exactly one type from them. They are gone from `@objectstack/spec`:
+  `environment` and `tenant` are re-declared in the cloud repo (objectstack-ai/cloud#2037), and
+  the other four are deleted outright — zero consumers in any repo (#16526, ruled A). All of it
+  is recoverable from git history at `d5d8d50db`.
+- **The package & marketplace format** — `package.zod`, `package-version.zod`, `marketplace.zod`,
+  `package-l10n`, `template-manifest.zod` (30 defs, 1400 lines). A package author needs it and the
+  open-source CLI's `os package publish` speaks it, so it STAYS, relocated to `src/marketplace/`
+  and published as `@objectstack/spec/marketplace`. Every def, key and JSON Schema is
+  byte-identical under the new `$id` category (`RENAMED_DEFS`, 32 entries; nothing left the
+  author-facing contract).
+
+## FROM → TO
+
+| you wrote | write instead |
+|:--|:--|
+| `import { PackageSchema, CreatePackageRequestSchema, … } from '@objectstack/spec/cloud'` | `… from '@objectstack/spec/marketplace'` — same symbols, same shapes |
+| `import { EnvironmentArtifactSchema } from '@objectstack/spec/cloud'` | `… from '@objectstack/spec/system'` (it was only ever a re-export of that declaration) |
+| `import type { EnvironmentType } from '@objectstack/spec/cloud'` | `… from '@objectstack/spec/api'` (re-declared beside the discovery fold table that reads it) |
+| `import { EnvironmentSchema, TenantPlanSchema, ProvisionEnvironmentRequestSchema, … } from '@objectstack/spec/cloud'` | no open-source replacement — these are the cloud repo's own declarations now |
+| `/docs/references/cloud/<page>` | `/docs/references/marketplace/<page>` for the format pages (redirected); the control-plane pages have no successor |
+
+Why the mis-binding hazard closes with this: `client.environments.*` keeps its erased `any`
+deliberately (#11925/#12036), and the camelCase `Environment` row used to be the obvious-looking
+binding for it — it compiled and read `undefined` at runtime against the snake_case wire. That
+type no longer exists in the open-source package, so the wrong binding is structurally
+impossible rather than warned about in a docblock.
+
+`@objectstack/cli` and `@objectstack/metadata` change only an import path (`marketplace` and
+`system` respectively); no behaviour moves.

apps/docs/redirects.mjs

@@ -128,7 +128,20 @@ export const docsRedirects = [
   ['/docs/guides/metadata', '/docs/concepts/metadata-driven'],
   ['/docs/guides/solutions', '/docs'],
   ['/docs/guides/cheatsheets', '/docs/getting-started/quick-reference'],
+  // `content/docs/references/cloud/` retired with the `@objectstack/spec/cloud`
+  // subpath (#16325). The package & marketplace format pages moved to
+  // `references/marketplace/`; the environment-artifact page documents the
+  // `system/` declaration it only ever re-exported; the cloud control plane's
+  // own contract pages (environment, environment-package, tenant,
+  // developer-portal, marketplace-admin, app-store) have no successor page —
+  // section index, same as the cloud-artifact-api entry above.
+  ['/docs/references/cloud/marketplace', '/docs/references/marketplace/marketplace'],
+  ['/docs/references/cloud/package', '/docs/references/marketplace/package'],
+  ['/docs/references/cloud/package-version', '/docs/references/marketplace/package-version'],
+  ['/docs/references/cloud/template-manifest', '/docs/references/marketplace/template-manifest'],
+  ['/docs/references/cloud/environment-artifact', '/docs/references/system/environment-artifact'],
   // folder moves (wildcards — keep after exact entries)
+  ['/docs/references/cloud/:path*', '/docs/references'],
   ['/docs/guides/runtime-services/:path*', '/docs/kernel/runtime-services/:path*'],
   ['/docs/guides/contracts/:path*', '/docs/kernel/contracts/:path*'],
   // ObjectOS layer-name retirement: the System Protocol section is now "kernel"

content/docs/concepts/north-star.mdx

@@ -62,7 +62,7 @@ validated against `ObjectStackDefinitionSchema`). When published to Cloud it is
 wrapped in the immutable environment artifact envelope defined by
 `EnvironmentArtifactSchema` in
 `packages/spec/src/system/environment-artifact.zod.ts` (the single
-declaration; `@objectstack/spec/cloud` re-exports it).
+declaration, published on `@objectstack/spec/system`).
 
 The artifact contains:
 

content/docs/deployment/troubleshooting.mdx

@@ -344,7 +344,7 @@ import { FieldSchema } from '@objectstack/spec/data';
 import { ErrorResponseSchema } from '@objectstack/spec/api';
 ```
 
-Available subpaths: `data`, `api`, `ui`, `system`, `kernel`, `ai`, `automation`, `contracts`, `integration`, `security`, `studio`, `cloud`, `qa`, `identity`, `shared`.
+Available subpaths (the `./*` entries of the package's `exports` map, in its order): `data`, `system`, `kernel`, `ai`, `automation`, `api`, `ui`, `contracts`, `integration`, `security`, `studio`, `marketplace`, `qa`, `identity`, `shared`, `meta-spelling`.
 
 ---
 

content/docs/getting-started/glossary.mdx

@@ -11,7 +11,7 @@ To navigate the ObjectStack ecosystem effectively, it is helpful to understand t
 The umbrella term for the entire suite of protocols and reference implementations. It is organized into **15 protocol namespaces** grouped into three architectural layers.
 
 ### Protocol Namespace
-A logical grouping of related schemas and types defined with Zod. ObjectStack has 15 protocol namespaces: Data, UI, System, Automation, AI, API, Identity, Security, Kernel, Cloud, QA, Contracts, Integration, Studio, and Shared.
+A logical grouping of related schemas and types defined with Zod. ObjectStack has 15 protocol namespaces: Data, UI, System, Automation, AI, API, Identity, Security, Kernel, Marketplace, QA, Contracts, Integration, Studio, and Shared.
 
 ---
 
@@ -22,7 +22,7 @@ The 15 namespaces collapse into three top-level layers:
 | Layer | Also called | Namespaces it includes | Purpose |
 | :--- | :--- | :--- | :--- |
 | **ObjectQL** | Data Layer | Data | Objects, fields, queries, relations, validation, data access |
-| **Kernel** | Control Layer / System Layer (formerly named "ObjectOS") | Kernel, System, Automation, AI, API, Identity, Security, Cloud, Integration, Studio, QA, Contracts, Shared | Runtime, permissions, automation, plugins, tenants, agent tools, artifact loading |
+| **Kernel** | Control Layer / System Layer (formerly named "ObjectOS") | Kernel, System, Automation, AI, API, Identity, Security, Marketplace, Integration, Studio, QA, Contracts, Shared | Runtime, permissions, automation, plugins, packages, agent tools, artifact loading |
 | **ObjectUI** | View Layer | UI | Apps, views, dashboards, actions, presentation metadata |
 
 Older docs and talks used **ObjectOS** as the name of this control layer. That name now refers exclusively to the commercial ObjectOS runtime environment ([docs.objectos.ai](https://docs.objectos.ai)); the open control layer is called the **Kernel**, described by the System/Kernel/AI/API protocol namespaces below.
@@ -58,8 +58,8 @@ User, organization, and position schemas for identity management.
 ### Security Protocol
 RBAC, permissions, policy, and access-control schemas.
 
-### Cloud Protocol
-Multi-tenant cloud, deployment, environment, and package distribution schemas.
+### Marketplace Protocol
+The package & marketplace format: package identity and translations, immutable package versions, marketplace listing / submission / install shapes, and the template manifest — what a package author publishes and what the marketplace answers with. The cloud control plane's own contracts (environments, tenants, deployment) are not an open-source protocol; they live in the cloud repo.
 
 ### QA Protocol
 Test, validation, and quality-assurance schemas.
@@ -172,7 +172,7 @@ A map within the UI Runtime that links a string identifier (e.g., `"chart.bar"`)
 ## Governance
 
 ### Tenant (Space / Workspace)
-A logical isolation unit in the Cloud Protocol for multi-tenancy, modeled by the `tenant` schema (`cloud/tenant.zod.ts`). A single ObjectStack instance can host multiple tenants. Data is segregated by tenant isolation strategies. "Space" and "Workspace" are informal aliases for the same concept.
+A logical isolation unit for multi-tenancy. Its `tenant` schema is a cloud control-plane contract declared in the cloud repo — it left `@objectstack/spec` with the `./cloud` subpath — so it is not one of the open-source protocol namespaces above. A single ObjectStack instance can host multiple tenants. Data is segregated by tenant isolation strategies. "Space" and "Workspace" are informal aliases for the same concept.
 
 ### FLS (Field-Level Security)
 A granular permission model (Security Protocol) where access control is applied to individual fields (columns), not just the whole object (row).

content/docs/getting-started/quick-reference.mdx

@@ -182,15 +182,18 @@ User identity, organizations, and position management.
 | **[Position](/docs/references/identity/position)** | `position.zod.ts` | Position | Permission-set distribution (岗位, ADR-0090) |
 | **[SCIM](/docs/references/identity/scim)** | `scim.zod.ts` | SCIMUser, SCIMGroup | SCIM 2.0 provisioning |
 
-## Cloud Protocol (3 of 11 schemas)
+## Marketplace Protocol (2 of 4 schemas)
 
-Environments, marketplace, licensing, and multi-tenancy.
+The package & marketplace format — what a package author publishes and what the
+marketplace answers with. (The cloud control plane's own contracts — environments,
+tenants, the developer portal, marketplace administration — are not an open-source
+protocol; they left `@objectstack/spec` with the `./cloud` subpath and live in the
+cloud repo beside their producer.)
 
 | Protocol | Source File | Key Schemas | Purpose |
 |:---------|:-----------|:------------|:--------|
-| **[Environment](/docs/references/cloud/environment)** | `environment.zod.ts` | Environment, EnvironmentType | Deployment environments |
-| **[Marketplace](/docs/references/cloud/marketplace)** | `marketplace.zod.ts` | MarketplaceListing, PackageSubmission | Plugin marketplace |
-| **[Tenant](/docs/references/cloud/tenant)** | `tenant.zod.ts` | Tenant | Multi-tenancy isolation |
+| **[Package](/docs/references/marketplace/package)** | `package.zod.ts` | Package, CreatePackageRequest, PackageTranslations | Package identity and listing text |
+| **[Marketplace](/docs/references/marketplace/marketplace)** | `marketplace.zod.ts` | MarketplaceListing, PackageSubmission | Plugin marketplace |
 
 ## Integration Protocol (1 of 1 schema)
 

content/docs/permissions/system-context.mdx

@@ -47,16 +47,17 @@ is left open deliberately rather than hidden — see
 
 ## Which `isSystem` this page is about
 
-Four unrelated declarations share the identifier. **This page documents only the
+Three unrelated declarations share the identifier. **This page documents only the
 first.** The others are ordinary metadata fields on a stored document and have
-nothing to do with elevation.
+nothing to do with elevation. (A fourth, `Environment.isSystem` — a
+platform-infrastructure environment, not user data — left this repo with the
+`@objectstack/spec/cloud` subpath in #16325 and is declared in the cloud repo.)
 
 | Declaration | What it is | This page? |
 |:---|:---|:---:|
 | `ExecutionContext.isSystem` — `packages/spec/src/kernel/execution-context.zod.ts#isSystem` | The elevation flag on an operation's context | ✅ |
 | `Object.isSystem` — `packages/spec/src/data/object.zod.ts#isSystem` | Marks a **system object** (protected from deletion; defaults its org-wide sharing to `public` when no `sharingModel` is set) | ❌ |
 | `EmailTemplate.isSystem` — `packages/spec/src/system/email-template.zod.ts#isSystem` | Built-in template; tenants may override but should not delete | ❌ |
-| `Environment.isSystem` — `packages/spec/src/cloud/environment.zod.ts#isSystem` | Platform-infrastructure environment, not user data | ❌ |
 
 The collision is a genuine hazard rather than a naming nit: `Object.isSystem`
 changes an object's **default sharing**, and `ExecutionContext.isSystem` changes
@@ -382,10 +383,10 @@ test files certifies nothing. ⛔ Do not re-add them to `DECLARED_COUNTS` — a
 self-test case in the gate refuses that by name. Re-measure them with
 `node scripts/isystem-census.mjs` when you want them current, and move the date.
 
-**What the enforced declarations row counts.** Not the four field declarations
-above — those are four *distinct fields* that happen to share a name, and only
+**What the enforced declarations row counts.** Not the three field declarations
+above — those are three *distinct fields* that happen to share a name, and only
 the first is elevation. This row counts every position where the parser puts the
-identifier in a **declaring** slot: those four, plus the structural type literals
+identifier in a **declaring** slot: those three, plus the structural type literals
 that restate `ExecutionContext.isSystem`'s shape inline rather than importing it
 (`{ isSystem: true; tenantId?: string }`, `context?: { isSystem?: boolean }`, and
 the `get isSystem()` accessor on the engine's context wrapper). A restatement is

content/docs/plugins/packages.mdx

@@ -24,7 +24,7 @@ ObjectStack is organized into **72 package manifests** across multiple categorie
 **The Constitution** — Protocol schemas, types, and constants for the entire ObjectStack ecosystem.
 
 - **Purpose**: Zod-first schema definitions for all 15 protocol domains
-- **Exports**: Builder functions (`defineStack`, `defineView`, `defineApp`, `defineFlow`, `defineAgent`, `defineTool`, `defineSkill`) from the root entry, plus `ObjectSchema.create()` for objects from the `@objectstack/spec/data` subpath. Protocol namespaces (Data, UI, System, Automation, AI, API, Identity, Security, Kernel, Cloud, QA, Contracts, Integration, Studio, Shared) are not re-exported from the top-level entry for tree-shaking reasons — import them from subpaths such as `@objectstack/spec/data` and `@objectstack/spec/ui`.
+- **Exports**: Builder functions (`defineStack`, `defineView`, `defineApp`, `defineFlow`, `defineAgent`, `defineTool`, `defineSkill`) from the root entry, plus `ObjectSchema.create()` for objects from the `@objectstack/spec/data` subpath. Protocol namespaces (Data, UI, System, Automation, AI, API, Identity, Security, Kernel, Marketplace, QA, Contracts, Integration, Studio, Shared) are not re-exported from the top-level entry for tree-shaking reasons — import them from subpaths such as `@objectstack/spec/data` and `@objectstack/spec/ui`.
 - **When to use**: Import types, schemas, and builder functions when authoring metadata.
 - **Documentation**: [Protocol Reference](/docs/references)
 

content/docs/references/api/discovery.mdx

@@ -12,8 +12,8 @@ description: Discovery protocol schemas
 ## TypeScript Usage
 
 ```typescript
-import { ApiRoutesSchema, CapabilityDescriptorSchema, DiscoverySchema, DiscoveryEnvironmentSchema, RouteHealthEntrySchema, RouteHealthReportSchema, ServiceInfoSchema, ServiceSelfInfoSchema, ServiceStatus, WellKnownCapabilitiesSchema } from '@objectstack/spec/api';
-import type { ApiRoutes, CapabilityDescriptor, DiscoveryEnvironment, RouteHealthEntry, RouteHealthReport, ServiceInfo, ServiceSelfInfo, ServiceStatus, WellKnownCapabilities } from '@objectstack/spec/api';
+import { ApiRoutesSchema, CapabilityDescriptorSchema, DiscoverySchema, DiscoveryEnvironmentSchema, EnvironmentTypeSchema, RouteHealthEntrySchema, RouteHealthReportSchema, ServiceInfoSchema, ServiceSelfInfoSchema, ServiceStatus, WellKnownCapabilitiesSchema } from '@objectstack/spec/api';
+import type { ApiRoutes, CapabilityDescriptor, DiscoveryEnvironment, EnvironmentType, RouteHealthEntry, RouteHealthReport, ServiceInfo, ServiceSelfInfo, ServiceStatus, WellKnownCapabilities } from '@objectstack/spec/api';
 
 // Validate data
 const result = ApiRoutesSchema.parse(data);
@@ -161,6 +161,23 @@ Deployment posture a discovery response advertises. Deliberately three coarse bu
 * `development`
 
 
+---
+
+## EnvironmentType
+
+Environment categorical tag (prod/sandbox/dev/test/…)
+
+### Allowed Values
+
+* `production`
+* `sandbox`
+* `development`
+* `test`
+* `staging`
+* `preview`
+* `trial`
+
+
 ---
 
 ## RouteHealthEntry