feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B)

.changeset/22130-protocol-18.md

@@ -0,0 +1,18 @@
+---
+'@objectstack/spec': major
+'@objectstack/mcp': patch
+---
+
+feat(spec)!: `PROTOCOL_VERSION` is `18.0.0`; the runtime handshake accepts `engines.protocol: '^18'` and refuses `'^17'`
+
+Clause-②: yes (narrowing: the handshake refuses a manifest pinned to protocol 17 (`'^17'`, `'^17.x.y'`, `'17.x'`), while the exported `PROTOCOL_VERSION` moves to `'18.0.0'` and a `'^18'` manifest is admitted)
+
+<!-- adr-0087: not-required (already-registered field-malformed-scale-precision-removed, record-chatter-position-vocabulary, element-input-target-variable-removed, element-filter-removed, element-form-removed, field-column-lists-canonicalized, metric-filters-removed, cube-sub-day-granularities-removed, cube-join-sql-and-relationship-removed, record-highlights-field-icon-removed, mapping-lookup-params-removed, translation-component-submit-label-removed, page-component-responsive-removed, object-grid-default-sort-removed, object-kanban-quick-add-removed, permission-allow-restore-purge-removed, form-view-option-default-removed, field-reference-to-alias, connector-error-mapping-removed, connector-connection-timeout-ms-removed, hook-timeout-to-timeout-ms, job-timeout-to-timeout-ms, api-endpoint-cache-ttl-to-cache-ttl-seconds, dashboard-refresh-interval-to-refresh-interval-seconds, connector-resilience-keys-removed, connector-triggers-removed, memory-persistence-auto-save-interval-to-ms, turso-config-timeout-to-timeout-ms, view-page-mount-removed, list-view-sort-string-clause-to-array, page-assigned-profiles-removed, chart-config-aria-removed, dashboard-widget-chart-config-structure-removed, translation-per-app-settings-removed, object-tenancy-organization-field-removed, page-component-filter-record-to-rule-array, view-item-owner-hidden-removed, report-joined-chart-removed, view-overlay-owner-hidden-removed, form-layout-inline-grid-to-vertical, currency-config-precision-removed, permission-rls-tags-removed, action-aria-removed, cube-member-inner-name-removed, flow-decision-mode-inclusive-explicit, view-list-tabs-removed, cube-refresh-key-removed, time-default-utc-suffix-dropped, page-header-breadcrumb-removed, connector-sync-keys-removed, form-view-subform-columns-canonicalized, action-block-endpoint-to-target, form-field-public-picker-removed, dataset-count-measure-empty-field-removed, agent-structured-output-refused-members-removed, translation-widget-sub-caption-removed, agent-memory-long-term-store-removed, agent-lifecycle-removed, object-grid-resizable-columns-removed, page-requires-non-compiled-kind-removed, element-text-variant-heading-levels, object-master-detail-form-detail-sort-field-removed, declared-index-unique-scope, manifest-permissions-string-list-removed) The protocol major moves, and that move publishes the already-registered step-18 chain as the current upgrade path: these are its 64 D2 conversions, which `os migrate meta --from 17` replays together with the step's 329 D3 semantic entries. Each entry was registered by the change that made its break, under that change's own disposition; this diff adds, renames and removes none. The one edit outside that chain is the manifest's `engines.protocol` range: it is the ADR-0087 D1 handshake's input rather than a metadata shape any conversion rewrites, and `os migrate meta --write` rewrites it from `'^17'` to `'^18'`. The other categories are closed on facts: the package publishes (not unpublished); a consumer has an edit to make (not no-migration-prescription); and an exported value and the load door move, not a TypeScript declaration alone (not runtime-interface-only or type-surface-only). -->
+
+**BREAKING**, graded `major`: Changesets is in pre mode (`next`) for the v18 line, so this ships in an `18.0.0-next.N` prerelease. The protocol major moves in this reviewed change, not in the version pass (ruling record 6049734955, Q1 → B). Until that line's first version pass, `PROTOCOL_VERSION` is one major ahead of the package version; `check-changeset-no-major.mjs` admits that only in pre mode with a pending `major` for `@objectstack/spec` (ruling record 6056808625).
+
+- **`PROTOCOL_VERSION` reads `'18.0.0'`** and `PROTOCOL_MAJOR` reads `18`. The ADR-0087 D1 handshake on every load and install door (the app load seam, `POST /api/v1/packages`, `POST /api/v1/marketplace/install-local`) now admits a package whose `engines.protocol` admits major 18, and refuses one pinned to 17 (`'^17'`, `'^17.x.y'`, `'17.x'`) with `OS_PROTOCOL_INCOMPATIBLE` (422), naming `objectstack migrate meta --from 17`.
+- **What you change.** Run `objectstack migrate meta --from 17` to list the edits for existing sources; `--write` applies the ones it can prove, including the declared `engines.protocol` range, rewritten in place from `'^17'` to `'^18'`, and you apply the rest by hand.
+- **`spec-changes.json` and the protocol upgrade guide** now carry the protocol 17 → 18 record, generated from the registries: 64 mechanical conversions and 329 semantic entries. The aggregate record spans 16 → 18.
+- **`os init`** stamps `'^18'` in the manifests it writes, and `os lint`'s `protocol/missing-engines-range` fix names `'^18'`. The `create-objectstack` template keeps `'^17'` until the version pass stamps it together with its `@objectstack/*` dependency ranges.
+- **`@objectstack/mcp`**: the README's `defineStack` examples declare `'^18'`.

content/docs/deployment/cli.mdx

@@ -2474,7 +2474,7 @@ export default defineStack({
     name: 'My App',
     description: 'My ObjectStack application',
     // Protocol major this app is authored against (ADR-0087 load-time check).
-    engines: { protocol: '^17' },
+    engines: { protocol: '^18' },
   },
 
   objects: Object.values(objects),

content/docs/getting-started/your-first-project.mdx

@@ -135,7 +135,7 @@ export default defineStack({
     type: 'app',
     name: 'My App',
     // Protocol major this app is authored against (ADR-0087 load-time check).
-    engines: { protocol: '^17' },
+    engines: { protocol: '^18' },
   },
   // `automation` runs flows and, per ADR-0097, materializes declarative
   // `connectors:` entries at boot. The three generic executors below register

content/docs/upgrading.mdx

@@ -156,7 +156,7 @@ runtime checks that handshake **first**, before it loads anything:
 ```ts
 manifest: {
   // ...
-  engines: { protocol: '^17' },
+  engines: { protocol: '^18' },
 }
 ```
 

examples/app-crm/objectstack.config.ts

@@ -45,7 +45,7 @@ export default defineStack({
     // Protocol major this package is authored against (ADR-0087). The kernel
     // checks the range at load time and refuses a major-incompatible runtime
     // with a structured diagnostic instead of failing deep in a schema parse.
-    engines: { protocol: '^17' },
+    engines: { protocol: '^18' },
   },
 
   // Auto-resolved by the CLI; `ui` enables the Studio shell, `automation`

examples/app-multi-package/src/packages/core/index.ts

@@ -19,7 +19,7 @@ export default defineStack({
     version: '1.0.0',
     type: 'app',
     description: 'The App half of a two-package release artifact (ADR-0130 D4)',
-    engines: { protocol: '^17' },
+    engines: { protocol: '^18' },
   },
 
   objects: [

examples/app-multi-package/src/packages/orders/index.ts

@@ -58,7 +58,7 @@ export default defineStack({
     version: '1.0.0',
     type: 'module',
     description: 'The Module half of a two-package release artifact (ADR-0130 D4)',
-    engines: { protocol: '^17' },
+    engines: { protocol: '^18' },
     // The App package this module extends. `resolveArtifactPackageOrder` reads
     // it as the topological edge that registers core BEFORE orders (ADR-0130
     // D5, ADR-0116's one sorter) — the array order below is not what decides.

examples/app-showcase/objectstack.config.ts

@@ -86,7 +86,7 @@ export default defineStack({
     // Protocol major this package is authored against (ADR-0087). The kernel
     // checks the range at load time and refuses a major-incompatible runtime
     // with a structured diagnostic instead of failing deep in a schema parse.
-    engines: { protocol: '^17' },
+    engines: { protocol: '^18' },
   },
 
   // Capability tokens the CLI resolves to platform plugins:

examples/app-todo/objectstack.config.ts

@@ -45,7 +45,7 @@ export default defineStack({
     // Protocol major this package is authored against (ADR-0087). The kernel
     // checks the range at load time and refuses a major-incompatible runtime
     // with a structured diagnostic instead of failing deep in a schema parse.
-    engines: { protocol: '^17' },
+    engines: { protocol: '^18' },
   },
 
   // Platform services this app needs — the closed `PLATFORM_CAPABILITY_TOKENS`

packages/cli/src/utils/author-time-rules.test.ts

@@ -61,7 +61,7 @@ const optionBStack = (reference: string): Record<string, unknown> => ({
 const perPackageOnlyStack = (): Record<string, unknown> => {
   const coreManifest = {
     id: 'com.example.obflip.core', name: 'obflip core', namespace: 'ob',
-    version: '1.0.0', type: 'app', engines: { protocol: '^17' },
+    version: '1.0.0', type: 'app', engines: { protocol: '^18' },
   };
   const coreObjects = [{
     name: 'ob_account', label: 'Account', pluralLabel: 'Accounts', sharingModel: 'private',
@@ -79,7 +79,7 @@ const perPackageOnlyStack = (): Record<string, unknown> => {
   }];
   const ordersManifest = {
     id: 'com.example.obflip.orders', name: 'obflip orders', namespace: 'ob',
-    version: '1.0.0', type: 'module', engines: { protocol: '^17' },
+    version: '1.0.0', type: 'module', engines: { protocol: '^18' },
     dependencies: { 'com.example.obflip.core': '^1.0.0' },
   };
   const ordersObjects = [{

packages/cli/src/utils/config-named-export-rule.test.ts

@@ -65,7 +65,7 @@ const MANIFEST = `{
     version: '0.1.0',
     type: 'app',
     name: 'Probe',
-    engines: { protocol: '^17' },
+    engines: { protocol: '^18' },
   }`;
 
 const roots: string[] = [];

packages/cli/src/utils/config-shadowed-named-export.test.ts

@@ -67,7 +67,7 @@ const MANIFEST = `{
     version: '0.1.0',
     type: 'app',
     name: 'Probe',
-    engines: { protocol: '^17' },
+    engines: { protocol: '^18' },
   }`;
 
 const roots: string[] = [];

packages/cli/test/authoring-rule-command-parity.test.ts

@@ -36,7 +36,7 @@ const cliBin = join(fileURLToPath(new URL('.', import.meta.url)), '..', 'bin', '
 
 /** A stack that satisfies the security linter, so only the planted defect gates. */
 const withBaseline = (stack: Record<string, unknown>) => ({
-  manifest: { id: 'com.example.parity', namespace: 'parity', version: '1.0.0', name: 'Parity', type: 'app', engines: { protocol: '^17' } },
+  manifest: { id: 'com.example.parity', namespace: 'parity', version: '1.0.0', name: 'Parity', type: 'app', engines: { protocol: '^18' } },
   ...stack,
 });
 

packages/cli/test/build-text-face-advisory-count.test.ts

@@ -157,7 +157,7 @@ const perPackageWarnings = (warnings: unknown[]): string[] =>
 const CONFIG_MULTI = `
 const coreManifest = {
   id: 'com.example.bcount.core', name: 'bcount core', namespace: 'bc',
-  version: '1.0.0', type: 'app', engines: { protocol: '^17' },
+  version: '1.0.0', type: 'app', engines: { protocol: '^18' },
 };
 const coreObjects = [{
   name: 'bc_account', label: 'Account', pluralLabel: 'Accounts', sharingModel: 'private',
@@ -176,7 +176,7 @@ const coreApps = [{
 
 const ordersManifest = {
   id: 'com.example.bcount.orders', name: 'bcount orders', namespace: 'bc',
-  version: '1.0.0', type: 'module', engines: { protocol: '^17' },
+  version: '1.0.0', type: 'module', engines: { protocol: '^18' },
   dependencies: { 'com.example.bcount.core': '^1.0.0' },
 };
 const ordersObjects = [{
@@ -223,7 +223,7 @@ import { defineStack } from '@objectstack/spec';
 export default defineStack({
   manifest: {
     id: 'com.example.bcsingle', name: 'bcsingle', namespace: 'bs',
-    version: '1.0.0', type: 'app', engines: { protocol: '^17' },
+    version: '1.0.0', type: 'app', engines: { protocol: '^18' },
   },
   objects: [{
     name: 'bs_thing', label: 'Thing', pluralLabel: 'Things', sharingModel: 'private',

packages/cli/test/flow-credential-literal-doors.e2e.test.ts

@@ -42,7 +42,7 @@ const stackOf = (literal: boolean) => ({
     version: '1.0.0',
     type: 'app',
     name: 'Credential door probe',
-    engines: { protocol: '^17' },
+    engines: { protocol: '^18' },
   },
   objects: [
     {

packages/cli/test/jsx-gate-manifest-notice.e2e.test.ts

@@ -141,7 +141,7 @@ function stack(body: string | null): string {
 import { defineStack } from '@objectstack/spec';
 
 export default defineStack({
-  manifest: { id: 'com.example.jxg', name: 'jxg', version: '1.0.0', type: 'app', namespace: 'jxg', engines: { protocol: '^17' } },
+  manifest: { id: 'com.example.jxg', name: 'jxg', version: '1.0.0', type: 'app', namespace: 'jxg', engines: { protocol: '^18' } },
   ${pages}
   apps: [{ name: 'jxg_app', label: 'JXG', navigation: [${nav}] }],
   objects: [
@@ -161,7 +161,7 @@ function packageCarried(top: string): string {
 import { defineStack } from '@objectstack/spec';
 
 export default defineStack({
-  manifest: { id: 'com.example.jxg', name: 'jxg', version: '1.0.0', type: 'app', namespace: 'jxg', engines: { protocol: '^17' } },
+  manifest: { id: 'com.example.jxg', name: 'jxg', version: '1.0.0', type: 'app', namespace: 'jxg', engines: { protocol: '^18' } },
   pages: ${top},
   packages: [
     {

packages/cli/test/lint-handwritten-checks-package-fold.test.ts

@@ -76,7 +76,7 @@ const MANIFEST = {
   version: '1.0.0',
   type: 'app',
   namespace: 'probe',
-  engines: { protocol: '^17' },
+  engines: { protocol: '^18' },
 };
 
 /** A module-scope binding, so the hook handler below cannot be lowered. */
@@ -286,7 +286,7 @@ describe('#17528 — os lint judges the stack the author declared, in either ADR
     });
     const manifest = {
       id: 'com.example.ob', name: 'ob', version: '1.0.0', type: 'app', namespace: 'ob',
-      engines: { protocol: '^17' },
+      engines: { protocol: '^18' },
     };
 
     const fromPackages = lintConfig({

packages/cli/test/lint-namespace-prefix-per-package.test.ts

@@ -74,7 +74,7 @@ const B = {
   id: 'com.example.b', name: 'b', version: '1.0.0', type: 'module', namespace: 'beta',
   dependencies: { 'com.example.a': '^1.0.0' },
 };
-const TOP = { ...A, engines: { protocol: '^17' } };
+const TOP = { ...A, engines: { protocol: '^18' } };
 
 const obj = () => ({
   name: 'ob_order', label: 'Order', sharingModel: 'private', nameField: 'number',

packages/cli/test/lint-per-package-authoring-parity.test.ts

@@ -122,7 +122,7 @@ const lintPerPackage = (issues: unknown[]): string[] =>
 const CONFIG_FLIP = `
 const coreManifest = {
   id: 'com.example.ppflip.core', name: 'ppflip core', namespace: 'pp',
-  version: '1.0.0', type: 'app', engines: { protocol: '^17' },
+  version: '1.0.0', type: 'app', engines: { protocol: '^18' },
 };
 const coreObjects = [{
   name: 'pp_account', label: 'Account', pluralLabel: 'Accounts', sharingModel: 'private',
@@ -141,7 +141,7 @@ const coreApps = [{
 
 const ordersManifest = {
   id: 'com.example.ppflip.orders', name: 'ppflip orders', namespace: 'pp',
-  version: '1.0.0', type: 'module', engines: { protocol: '^17' },
+  version: '1.0.0', type: 'module', engines: { protocol: '^18' },
   dependencies: { 'com.example.ppflip.core': '^1.0.0' },
 };
 const ordersObjects = [{
@@ -193,7 +193,7 @@ import { defineStack } from '@objectstack/spec';
 export default defineStack({
   manifest: {
     id: 'com.example.ppsingle', name: 'ppsingle', namespace: 'ps',
-    version: '1.0.0', type: 'app', engines: { protocol: '^17' },
+    version: '1.0.0', type: 'app', engines: { protocol: '^18' },
   },
   objects: [{
     name: 'ps_thing', label: 'Thing', pluralLabel: 'Things', sharingModel: 'private',

packages/cli/test/lint-per-package-authoring-seam.test.ts

@@ -83,7 +83,7 @@ function twoPackageArtifact(): Record<string, unknown> {
       namespace: 'pp',
       version: '1.0.0',
       type: 'app',
-      engines: { protocol: '^17' },
+      engines: { protocol: '^18' },
     },
     objects: [
       {
@@ -119,7 +119,7 @@ function twoPackageArtifact(): Record<string, unknown> {
       namespace: 'pp',
       version: '1.0.0',
       type: 'module',
-      engines: { protocol: '^17' },
+      engines: { protocol: '^18' },
       dependencies: { 'com.example.lintseam.core': '^1.0.0' },
     },
     objects: [
@@ -161,7 +161,7 @@ function singlePackageStack(): Record<string, unknown> {
       namespace: 'ps',
       version: '1.0.0',
       type: 'app',
-      engines: { protocol: '^17' },
+      engines: { protocol: '^18' },
     },
     objects: [
       {