Skip to content

Commit 03e5f4c

Browse files
hotlonghotlong
committed
Merge remote-tracking branch 'origin/main' into claude/issue-20594-hono-server-citations
2 parents 91ce7e5 + fbec216 commit 03e5f4c

26 files changed

Lines changed: 505 additions & 98 deletions

‎.changeset/20646-cli-migrate-meta-migrations-entry.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@objectstack/cli': patch
3+
---
4+
5+
fix(cli): `os migrate meta` takes the migration chain from `@objectstack/spec/migrations` (#20646)
6+
7+
`@objectstack/spec` moved the ADR-0087 migration chain and change-manifest names (`applyMetaMigrations`, `composeSpecChanges`, `MigrationFloorError`, `MIGRATION_MAJORS`, `MIGRATION_SUPPORT_FLOOR`, …) off the package root into the new `@objectstack/spec/migrations` entry, so the command now imports them from there. It replays the same chain and prints the same guidance; nothing a user types or reads changes.

‎.changeset/20646-migrations-entry-split.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
'@objectstack/spec': minor
3+
---
4+
5+
feat(spec)!: the ADR-0087 migration chain leaves the package root for the new `@objectstack/spec/migrations` entry (#20646)
6+
7+
**BREAKING** — the migration chain and change-manifest names (ADR-0087 D3/D4), with their types, are no longer exported from the package root `@objectstack/spec`. They are exported, unchanged, from the new entry `@objectstack/spec/migrations`.
8+
9+
A `major`-class change — an existing import path stops resolving for these names — recorded as `minor` under the launch-window convention.
10+
11+
**Why.** The migration registry is mostly the guidance text `objectstack migrate meta` prints, and the root re-exported it. The registry does work when its module loads (the list of majors and each step's rationale are computed then), so no bundler could prove it unused, and all of that text rode in every bundle of the root, whatever the consumer imported. This is the source-side payback of the Studio console's first-screen ceiling raise that the maintainer ruled on the 17.5.0 upgrade. Measured on the splitting PR against its merge base `1a75e39d4a` (tsup build, gzip -9):
12+
13+
| | before | after |
14+
| --- | --- | --- |
15+
| `dist/index.js` (CommonJS root) | 3,780,033 B / 1,067,061 B gzip | 2,009,810 B / 565,386 B gzip |
16+
| `dist/browser/index.mjs` (the ESM root a browser bundler pulls) | 3,764,293 B / 1,065,388 B gzip | 1,994,748 B / 563,787 B gzip |
17+
| a browser bundle of the ten names the Studio console imports from the root (rolldown, minified) | 700,884 B gzip | 301,287 B gzip |
18+
19+
The ADR-0087 **conversion layer stays on the root**: `defineStack` and `normalizeStackInput` read it at run time, so its names (`ALL_CONVERSIONS`, `CONVERSIONS_BY_MAJOR`, `applyConversions`, `applyConversionsToFlow`, `applyConversionsToStoredItem`, `collectConversionNotices`, the `CONVERSION_*_CODE` constants and their types) import from `@objectstack/spec` exactly as before.
20+
21+
### FROM → TO
22+
23+
| removed from `@objectstack/spec` | import instead from |
24+
| --- | --- |
25+
| `MIGRATIONS_BY_MAJOR`, `MIGRATION_MAJORS`, `MIGRATION_SUPPORT_FLOOR` | `@objectstack/spec/migrations` |
26+
| `RETIRED_KEYS_BY_MAJOR`, `RETIRED_DEFS_BY_MAJOR` | `@objectstack/spec/migrations` |
27+
| `applyMetaMigrations`, `composeMigrationChain`, `MigrationFloorError` | `@objectstack/spec/migrations` |
28+
| `composeSpecChanges`, `composeReleaseChanges` | `@objectstack/spec/migrations` |
29+
| `SpecChangesSchema`, `SpecConvertedSchema`, `SpecMigratedSchema`, `SpecSurfaceAddSchema`, `SpecSurfaceRemoveSchema`, `SpecReleaseChangesSchema`, `SpecReleaseSurfaceSchema` | `@objectstack/spec/migrations` |
30+
| types `MigrationStep`, `MigrationApplication`, `MigrationChainResult`, `MigrationHopResult`, `MigrationTodo`, `SemanticMigration`, `SpecChanges`, `SpecConverted`, `SpecMigrated`, `SpecSurfaceAdd`, `SpecSurfaceRemove`, `SpecReleaseChanges`, `SpecReleaseSurface`, `SurfaceDiff`, `ReleaseSurfaceDiff`, `PreviousReleaseRegistries` | `@objectstack/spec/migrations` |
31+
32+
**The one-line fix: change the import path.**
33+
34+
```ts
35+
// before
36+
import { applyMetaMigrations, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec';
37+
// after
38+
import { applyMetaMigrations, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec/migrations';
39+
```
40+
41+
The compiler finds every site: `TS2305` ("Module '"@objectstack/spec"' has no exported member …"); at run time the binding is `undefined`. Nothing else changes: the chain, its steps and semantic entries, the retired-key and retired-def tables and the change-manifest schemas are the same objects, and `objectstack migrate meta` replays the same chain.
42+
43+
⚠️ **Out-of-repo consumers are NOT MEASURED beyond objectui.** Inside this repository the moved names had five importers — `os migrate meta` (the only runtime one) and four tests — all moved in the same PR. objectui at the pinned `.objectui-sha` imports none of the moved names from anywhere. The `cloud` repository was not measured.
44+
45+
The ADR-0087 D3 semantic entry `migrations-entry-split` carries the judgement: an import path is TypeScript source, not metadata, so there is no source a D2 conversion could rewrite.
46+
47+
Clause-②: yes (narrowing)
48+
49+
<!-- adr-0087: registered migrations-entry-split -->

‎content/docs/deployment/troubleshooting.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -345,7 +345,7 @@ import { FieldSchema } from '@objectstack/spec/data';
345345
import { ErrorResponseSchema } from '@objectstack/spec/api';
346346
```
347347

348-
Available subpaths (the `./*` entries of the package's `exports` map, in its order): `data`, `system`, `kernel`, `ai`, `automation`, `api`, `api-assembled`, `ui`, `contracts`, `integration`, `security`, `studio`, `marketplace`, `qa`, `identity`, `shared`, `meta-spelling`.
348+
Available subpaths (the `./*` entries of the package's `exports` map, in its order): `data`, `system`, `kernel`, `ai`, `automation`, `api`, `api-assembled`, `ui`, `contracts`, `integration`, `security`, `studio`, `marketplace`, `qa`, `identity`, `shared`, `meta-spelling`, `migrations`.
349349

350350
---
351351

‎packages/cli/src/commands/migrate/meta.report-order.test.ts‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,15 +35,13 @@
3535

3636
import { stripVTControlCharacters } from 'node:util';
3737
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
38+
import { ObjectStackDefinitionSchema, formatZodIssue, normalizeStackInput } from '@objectstack/spec';
3839
import {
39-
ObjectStackDefinitionSchema,
4040
applyMetaMigrations,
41-
formatZodIssue,
42-
normalizeStackInput,
4341
MIGRATION_MAJORS,
4442
MIGRATION_SUPPORT_FLOOR,
4543
type MigrationChainResult,
46-
} from '@objectstack/spec';
44+
} from '@objectstack/spec/migrations';
4745
import { PROTOCOL_MAJOR } from '@objectstack/spec/kernel';
4846
import { printMigrationReport, type MigrationReport } from './meta.js';
4947

‎packages/cli/src/commands/migrate/meta.ts‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,15 @@ import { writeFileSync } from 'node:fs';
55
import { resolve } from 'node:path';
66
import { createInterface } from 'node:readline';
77
import chalk from 'chalk';
8+
import { ObjectStackDefinitionSchema, formatZodIssue, normalizeStackInput } from '@objectstack/spec';
89
import {
9-
ObjectStackDefinitionSchema,
1010
applyMetaMigrations,
1111
composeSpecChanges,
12-
formatZodIssue,
13-
normalizeStackInput,
1412
MigrationFloorError,
1513
MIGRATION_MAJORS,
1614
MIGRATION_SUPPORT_FLOOR,
1715
type MigrationChainResult,
18-
} from '@objectstack/spec';
16+
} from '@objectstack/spec/migrations';
1917
import { PROTOCOL_MAJOR, PROTOCOL_VERSION } from '@objectstack/spec/kernel';
2018
import { FILE_REFERENCE_TYPES, REFERENCE_VALUE_TYPES, STRUCTURED_JSON_TYPES } from '@objectstack/spec/data';
2119
import { FILE_REFERENCES_MIGRATION_ID, VALUE_SHAPES_MIGRATION_ID } from '@objectstack/spec/system';

‎packages/cli/test/migrate-meta-default-range.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
5151
import { tmpdir } from 'node:os';
5252
import { join, resolve } from 'node:path';
5353
import { fileURLToPath } from 'node:url';
54-
import { MIGRATIONS_BY_MAJOR, MIGRATION_MAJORS, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec';
54+
import { MIGRATIONS_BY_MAJOR, MIGRATION_MAJORS, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec/migrations';
5555
import { PROTOCOL_MAJOR } from '@objectstack/spec/kernel';
5656
import { childEnv } from './helpers/serve-process.js';
5757

‎packages/cli/test/migrate-meta-engine-guidance.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
5959
import { tmpdir } from 'node:os';
6060
import { join, resolve } from 'node:path';
6161
import { fileURLToPath } from 'node:url';
62-
import { MIGRATIONS_BY_MAJOR, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec';
62+
import { MIGRATIONS_BY_MAJOR, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec/migrations';
6363
import { childEnv } from './helpers/serve-process.js';
6464

6565
const execFileP = promisify(execFile);

‎packages/metadata-protocol/src/protocol.stored-migration.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ import { describe, expect, it } from 'vitest';
2626
// of this package's (file, verb) pairs sat in the gate's DEBT ledger until
2727
// #5619 sank the two predicates into a package both sides already depend on.
2828
import { assertEngineDeleteDispatch, assertEngineUpdateDispatch, assertEngineFindOnePredicate } from '@objectstack/metadata-core';
29-
import { applyMetaMigrations } from '@objectstack/spec';
29+
import { applyMetaMigrations } from '@objectstack/spec/migrations';
3030
import { ObjectStackProtocolImplementation } from './protocol.js';
3131
import {
3232
DECISION_MODE_REVIEW_CONVERSION_ID,

‎packages/services/service-automation/src/builtin/decision-overlapping-edge-conditions.pin.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
22

33
import { describe, it, expect, beforeEach } from 'vitest';
4-
import { ALL_CONVERSIONS, applyMetaMigrations } from '@objectstack/spec';
4+
import { ALL_CONVERSIONS } from '@objectstack/spec';
5+
import { applyMetaMigrations } from '@objectstack/spec/migrations';
56
import { AutomationEngine } from '../engine.js';
67
import { registerLogicNodes } from './logic-nodes.js';
78

‎packages/spec/api-surface/migrations.json‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{
2+
"description": "Every exported `name (kind)` of one published entry point of @objectstack/spec — the breadth half of the ADR-0059 backward-compatibility gate. Sharded by entry point (#5837) so two PRs touching different entry points never share a file. Reads the BUILT dist/*.d.ts: regenerate with `pnpm --filter @objectstack/spec gen:api-surface` after a real build.",
3+
"entry": "./migrations",
4+
"exports": [
5+
"MIGRATIONS_BY_MAJOR (const)",
6+
"MIGRATION_MAJORS (const)",
7+
"MIGRATION_SUPPORT_FLOOR (const)",
8+
"MigrationApplication (interface)",
9+
"MigrationChainResult (interface)",
10+
"MigrationFloorError (class)",
11+
"MigrationHopResult (interface)",
12+
"MigrationStep (interface)",
13+
"MigrationTodo (interface)",
14+
"PreviousReleaseRegistries (interface)",
15+
"RETIRED_DEFS_BY_MAJOR (const)",
16+
"RETIRED_KEYS_BY_MAJOR (const)",
17+
"ReleaseSurfaceDiff (interface)",
18+
"SemanticMigration (interface)",
19+
"SpecChanges (type)",
20+
"SpecChangesSchema (const)",
21+
"SpecConverted (type)",
22+
"SpecConvertedSchema (const)",
23+
"SpecMigrated (type)",
24+
"SpecMigratedSchema (const)",
25+
"SpecReleaseChanges (type)",
26+
"SpecReleaseChangesSchema (const)",
27+
"SpecReleaseSurface (type)",
28+
"SpecReleaseSurfaceSchema (const)",
29+
"SpecSurfaceAdd (type)",
30+
"SpecSurfaceAddSchema (const)",
31+
"SpecSurfaceRemove (type)",
32+
"SpecSurfaceRemoveSchema (const)",
33+
"SurfaceDiff (interface)",
34+
"applyMetaMigrations (function)",
35+
"composeMigrationChain (function)",
36+
"composeReleaseChanges (function)",
37+
"composeSpecChanges (function)"
38+
]
39+
}

0 commit comments

Comments
 (0)