docs: TypeScript legacy node10 resolution is unsupported for the 15 packages with subpath exports

.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.

packages/platform-objects/README.md

@@ -7,3 +7,5 @@ import { PlatformObjectsPlugin } from '@objectstack/platform-objects';
 ```
 
 Documentation: [Packages](https://objectstack.ai/docs/plugins/packages)
+
+**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).

packages/plugins/plugin-auth/README.md

@@ -4,6 +4,8 @@ Authentication & Identity Plugin for ObjectStack.
 
 > **✨ Status:** ObjectQL-based authentication implementation! Uses ObjectQL for data persistence (no third-party ORM required). Core authentication structure is in place with better-auth v1.4.18.
 
+**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
 
 ### Currently Implemented

packages/plugins/plugin-webhooks/README.md

@@ -7,3 +7,5 @@ import { WebhookOutboxPlugin } from '@objectstack/plugin-webhooks';
 ```
 
 Documentation: [Webhooks](https://objectstack.ai/docs/automation/webhooks)
+
+**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).

packages/services/service-cluster/README.md

@@ -9,3 +9,5 @@ import { ClusterServicePlugin } from '@objectstack/service-cluster';
 Documentation: [Cluster](https://objectstack.ai/docs/kernel/cluster)
 
 `@objectstack/service-cluster/testing` (the pub/sub, lock, KV and counter contract suites) is **ESM-only**: it imports `vitest`, whose own `require()` entry throws, so the subpath declares only an `import` condition. Load it with `import`; `require()` is refused with `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+
+**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).

packages/services/service-datasource/README.md

@@ -14,6 +14,8 @@ because the runtime admin was once private; now that both are open-source, they
 are one package. The two plugins still mount independently — merging the package
 did not couple them.)
 
+**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).
+
 ## Open-source mechanism, injectable tier line
 
 This package is mechanism only. Credential storage is delegated to a

packages/spec/README.md

@@ -4,6 +4,8 @@
 
 The **Source of Truth** for the ObjectStack Protocol. Contains strictly typed Zod schemas that define every aspect of the system.
 
+**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).
+
 ## Protocols
 
 - **System**: Manifests, Datasources, APIs.

packages/types/README.md

@@ -237,6 +237,8 @@ This package is designed to work with TypeScript 5.0+:
 }
 ```
 
+**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).
+
 ## Best Practices
 
 ### 1. Use Type-Only Imports