docs: TypeScript legacy node10 resolution is unsupported for the 15 packages with subpath exports (#26378)

<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi941YjangeAFXEgevqVv4bY9)_
Fixes #26208
Clause-②: no
Metadata-protocol: none

## 维护者速读

- 改了什么：插件开发指南加一段「Module resolution」，15 个带子路径 exports 的已发布包 README
各加一行：TypeScript 老的 node10 解析不支持，请用 node16、nodenext 或 bundler。
- 为什么改：按裁决 A（6422810199）落地。node10 不读 exports，用这种配置的使用方 import
子路径时类型静默找不到。
- 风险与回滚：只改文档和 README，不动 exports、不加 typesVersions、不加门禁。回滚即 revert 本 PR。
-
先看：content/docs/plugins/development.mdx（新段落），packages/spec/README.md（README
行的样子），.changeset/26208-node10-resolution-unsupported.md。
- 两分钟验证：`pnpm check:published-readme-links`，预期 0
root-relative、锚点全部解析（含新的 #module-resolution）。
- 需要你做的：无，席位落地。

## What changes

- `content/docs/plugins/development.mdx`: a `### Module resolution`
paragraph right under the Step 1 `tsconfig.json` block (the page already
shows `moduleResolution: "bundler"`). It states that the published
packages declare entry points only through `exports`, that `node10`
(`"node"`, the default under `module: commonjs`) ignores `exports` and
is unsupported, and that `bundler`, `node16` or `nodenext` is required.
Chosen over `content/docs/getting-started/**`: no page there covers
TypeScript setup, and open work holds that tree (the seat-3 hand-over
6430890935 names the collisions).
- One identical line in the README of each of the 15 packages, linking
to that anchor. Placed before the first `##` heading (after the intro),
appended at the end for the three READMEs that have no `##` heading
(platform-objects, plugin-webhooks, service-cluster), and under the
existing "TypeScript Configuration" section in
`packages/types/README.md`.
- Root changeset: one `patch` for the 15 packages, because each README
is in its package's `files[]` and ships in the tarball.

## Acceptance notes

- Premise re-read on `origin/main` 6390fe5: every one of the 15
packages still has subpath `exports` (spec 19, platform-objects 10,
metadata 5, cli 2, lint 2, plugin-auth 2, the other nine 1 each), and no
`packages/**/package.json` declares `typesVersions` (0 files). After
#26321 and #26352, metadata-core, service-cluster and cli still carry
subpaths, so none was dropped from the list.
- A scan of every non-private `packages/**/package.json` finds exactly
these 15 published packages with subpath exports, so the list is
complete on this tree.
- Evidence for the claim: the attw 0.18.5 `NoResolution@node10` reading
on PR #26198 (os-dev report 6419735271).
- Out of scope, untouched: no `exports` or `typesVersions` change, no
new check, no `ui/` path.

## Verification

At head 894bdb3.

<details><summary>Derived gate families: 92 derived, 92 run, 0
NOT-MEASURED</summary>

`node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
--ran FILE` printed: `✓ dispatch-gates --ran: 92 derived famil(ies)
accounted for — 92 run, 0 NOT-MEASURED (a DERIVED zero — all 92 recorded
an exit code and none of them is 3).`

Two families first exited on shallow-clone prerequisites
(`check-engine-split-ratio --days 90` exit 2,
`check-plugin-teardown-shape --self-test` exit 3); after deepening the
clone both exit 0. The build-reading families (`check:dts-closure`,
`check:dual-build-cjs-loads`, `check:i18n`, spec `check:docs`,
`check:skill-examples`) ran after a locked `turbo run build
--filter='./packages/**'` (VERDICT command-exit 0) and exit 0.
</details>

<details><summary>Acceptance gates</summary>

- `pnpm check:published-readme-links` exit 0: `567 outbound link(s)
across 159 published markdown file(s): 0 root-relative, 0 non-canonical
origin(s), 62 docs-site page(s) resolved (0 via redirect), 17 anchor(s)
verified`.
- `pnpm check:published-readme-exports` exit 0 (run on the built tree;
outside the derivation, run because the card names it).
- `pnpm check:doc-anchors` exit 0: 598 internal fragment links all
resolve.
- `pnpm check:doc-authoring` exit 0.
- lychee (`check-links.yml`) not run locally; the docs paragraph adds no
outbound link. Read from this PR's check-runs.
</details>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01ADHkmRdDB2C42HgHcE5Vrt

---
_Generated by [Claude
Code](https://claude.ai/code/session_01ADHkmRdDB2C42HgHcE5Vrt)_

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

Author: objectstack-fleet[bot]

.changeset/26208-node10-resolution-unsupported.md

@@ -0,0 +1,26 @@
+---
+'@objectstack/spec': patch
+'@objectstack/cli': patch
+'@objectstack/connector-imap': patch
+'@objectstack/core': patch
+'create-objectstack': patch
+'@objectstack/lint': patch
+'@objectstack/metadata': patch
+'@objectstack/metadata-core': patch
+'@objectstack/objectql': patch
+'@objectstack/platform-objects': patch
+'@objectstack/plugin-auth': patch
+'@objectstack/plugin-webhooks': patch
+'@objectstack/service-cluster': patch
+'@objectstack/service-datasource': patch
+'@objectstack/types': patch
+---
+
+docs: TypeScript's legacy `node10` module resolution is unsupported for packages with subpath exports
+
+Clause-②: no
+Metadata-protocol: none
+
+These fifteen packages declare their entry points only through `exports`, including subpaths such as `@objectstack/spec/kernel`. TypeScript's legacy `node10` resolution (`moduleResolution: "node"`, the default when `module` is `commonjs`) ignores `exports`, so a project configured that way cannot resolve the types of any subpath import, while the root entry still appears to work. Each package's README now says so in one line, and the plugin development guide gains a "Module resolution" paragraph. No `exports` map changes and no `typesVersions` fallback is added.
+
+What to do: set `moduleResolution` to `node16`, `nodenext` or `bundler` in the consuming project's `tsconfig.json`.

content/docs/plugins/development.mdx

@@ -53,6 +53,10 @@ Create `tsconfig.json`:
 }
 ```
 
+### Module resolution
+
+The published `@objectstack/*` packages declare their entry points only through `exports`, including subpaths such as `@objectstack/spec/kernel`. Set `moduleResolution` to `bundler` (as above), `node16` or `nodenext`. TypeScript's legacy `node10` resolution (spelled `"node"`, and the default when `module` is `commonjs`) is not supported: it ignores `exports`, so every subpath import fails to resolve its types while the root entry still appears to work. The packages ship no `typesVersions` fallback for it.
+
 ---
 
 ## Step 2: Define the Package Manifest

packages/cli/README.md

@@ -4,6 +4,8 @@ Command Line Interface for building metadata-driven applications with the Object
 
 Built on [oclif](https://oclif.io/) — commands are auto-discovered, and plugins can extend the CLI without modifying the main package.
 
+**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution).
+
 ## Installation
 
 ```bash

packages/connectors/connector-imap/README.md

@@ -4,6 +4,8 @@ The IMAP connector of ObjectStack's inbound mail: a **read-only IMAP4rev1 sessio
 
 It registers no `connector_action` handlers and ships no plugin: nothing in a flow calls IMAP; the mailbox service does.
 
+**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution).
+
 ## What it provides
 
 - **`openImapSession({ account, credentials, timeoutMs?, maxLiteralBytes?, maxCommandBytes? })`** — connects, reads the greeting, learns the server's capabilities, resolves the credential and authenticates. The session it answers:

packages/core/README.md

@@ -5,6 +5,8 @@
 [![npm](https://img.shields.io/npm/v/@objectstack/core.svg)](https://www.npmjs.com/package/@objectstack/core)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](../../LICENSING.md)
 
+**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution).
+
 ## Overview
 
 `@objectstack/core` is the foundation every ObjectStack runtime is built on. It hosts two kernels, a plugin lifecycle, a typed service registry, a structured logger, and a plugin-to-plugin event bus:

packages/create-objectstack/README.md

@@ -6,6 +6,8 @@ Scaffold a new [ObjectStack](https://objectstack.ai) project in seconds.
 npm create objectstack@latest my-app
 ```
 
+**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution).
+
 ## Usage
 
 ```bash

packages/lint/README.md

@@ -11,6 +11,8 @@ generated metadata to the same bar as hand-authored metadata.
 Dependency direction is one-way — `lint` → `@objectstack/spec` (the contract).
 It never depends on a runtime and is never bundled into a frontend.
 
+**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution).
+
 ## API
 
 - `validateWidgetBindings(stack)` — dashboard widget → dataset → measure/dimension

packages/metadata-core/README.md

@@ -12,6 +12,8 @@ access, no database driver. Implementations live in:
 - `@objectstack/metadata` (`FileSystemRepository`, `LayeredRepository`)
 - `@objectstack/metadata-postgres` (M1+)
 
+**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution).
+
 ## Exports
 
 ```typescript

packages/metadata/README.md

@@ -6,6 +6,8 @@
 
 It implements the **`IMetadataService`** contract from `@objectstack/spec` and acts as the single source of truth that all other packages depend on.
 
+**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution).
+
 ## Architecture Overview
 
 ```

packages/objectql/README.md

@@ -2,6 +2,8 @@
 
 The **Data Engine** for ObjectStack. It acts as a semantic layer between your application code and the underlying database.
 
+**TypeScript:** use `moduleResolution` `node16`, `nodenext` or `bundler`. The legacy `node10` resolution (`"node"`) ignores `exports`, so it cannot resolve this package's subpath imports and is not supported. See [Module resolution](https://objectstack.ai/docs/plugins/development#module-resolution).
+
 ## Features
 
 - **Universal API**: A consistent query interface (`find`, `insert`, `update`, `delete`) regardless of the storage backend.