refactor!: tighten v1 api surface

Author: aallam

.changeset/tidy-v1-api-surface.md

@@ -0,0 +1,7 @@
+---
+"@execbox/core": minor
+"@execbox/quickjs": minor
+"@execbox/remote": minor
+---
+
+Tighten the pre-1.0 public API surface by keeping low-level core helpers out of the main `@execbox/core` entrypoint, removing unsupported QuickJS runner subpath exports, and keeping runner-side remote endpoint types with `@execbox/quickjs/remote-endpoint`.

docs/src/content/docs/architecture/execbox-core.md

@@ -23,7 +23,7 @@ The core package exposes three main responsibilities:
 - Define the stable app-facing execution contract
 - Provide runtime implementers with shared runner semantics through `@execbox/core/runtime`
 
-The main public concepts are:
+The main app-facing concepts are:
 
 | Concept                | Purpose                                                                             |
 | ---------------------- | ----------------------------------------------------------------------------------- |
@@ -32,8 +32,10 @@ The main public concepts are:
 | `Executor`             | Runtime-specific implementation of `execute(code, providers)`                       |
 | `ExecuteResult`        | Stable success/error envelope returned by every executor                            |
 | `ToolExecutionContext` | Abort-aware metadata passed to each tool invocation                                 |
-| `ProviderManifest`     | Transport-safe view of a resolved provider exposed to reusable runners              |
-| `ToolCallResult`       | Trusted host response to a runner-emitted tool call                                 |
+
+Runtime implementer concepts such as `ProviderManifest` and `ToolCallResult`
+live on `@execbox/core/runtime` and `@execbox/core/protocol`, not the main
+`@execbox/core` entrypoint.
 
 ## Provider Resolution Pipeline
 

packages/core/__tests__/core/jsonSchema.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { generateTypesFromJsonSchema } from "@execbox/core";
+import { generateTypesFromJsonSchema } from "../../src/typegen/jsonSchema";
 
 describe("generateTypesFromJsonSchema", () => {
   it("emits namespace declarations for object schemas with required and optional fields", () => {

packages/core/__tests__/core/runtimeEntrypoint.test.ts

@@ -12,9 +12,15 @@ describe("@execbox/core/runtime", () => {
   });
 
   it("keeps executor-author helpers out of the app-facing core entrypoint", () => {
+    expect(core).not.toHaveProperty("assertValidIdentifier");
     expect(core).not.toHaveProperty("createToolCallDispatcher");
     expect(core).not.toHaveProperty("createTimeoutExecuteResult");
     expect(core).not.toHaveProperty("formatConsoleLine");
+    expect(core).not.toHaveProperty("generateTypesFromJsonSchema");
+    expect(core).not.toHaveProperty("isJsonSerializable");
     expect(core).not.toHaveProperty("normalizeThrownMessage");
+    expect(core).not.toHaveProperty("sanitizeIdentifier");
+    expect(core).not.toHaveProperty("sanitizeToolName");
+    expect(core).not.toHaveProperty("serializePropertyName");
   });
 });

packages/core/__tests__/core/sanitize.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { sanitizeIdentifier, sanitizeToolName } from "@execbox/core";
+import { sanitizeIdentifier } from "../../src/identifier";
+import { sanitizeToolName } from "../../src/sanitize";
 
 describe("sanitizeToolName", () => {
   it("replaces punctuation and spaces with underscores", () => {

packages/core/__tests__/security/isJsonSerializable.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { isJsonSerializable } from "@execbox/core";
+import { isJsonSerializable } from "@execbox/core/runtime";
 
 function buildDag(depth: number): Record<string, unknown> {
   let current: Record<string, unknown> = { leaf: true };

packages/core/etc/execbox-core.api.md

@@ -7,9 +7,6 @@
 import { ZodRawShape } from 'zod';
 import { ZodTypeAny } from 'zod';
 
-// @public
-export function assertValidIdentifier(value: string, label?: string): void;
-
 // @public
 export interface ExecuteError {
     code: ExecuteErrorCode;
@@ -79,44 +76,12 @@ export interface ExecutorRuntimeOptions {
     timeoutMs?: number;
 }
 
-// @public
-export function generateTypesFromJsonSchema(providerName: string, tools: Record<string, TypegenToolDescriptor>): string;
-
 // @public
 export function isExecuteFailure(value: unknown): value is ExecuteFailure;
 
-// @public
-export function isJsonSerializable(value: unknown, active?: Set<object>, memo?: WeakSet<object>): boolean;
-
-// @public
-export function isReservedWord(value: string): boolean;
-
-// @public
-export function isValidIdentifier(value: string): boolean;
-
 // @public
 export type JsonSchema = Record<string, unknown>;
 
-// @public
-export interface ProviderManifest {
-    // (undocumented)
-    name: string;
-    // (undocumented)
-    tools: Record<string, ProviderToolManifest>;
-    // (undocumented)
-    types: string;
-}
-
-// @public
-export interface ProviderToolManifest {
-    // (undocumented)
-    description?: string;
-    // (undocumented)
-    originalName: string;
-    // (undocumented)
-    safeName: string;
-}
-
 // @public
 export interface ResolvedToolDescriptor {
     description?: string;
@@ -139,34 +104,6 @@ export interface ResolvedToolProvider {
 // @public
 export function resolveProvider(provider: ToolProvider): ResolvedToolProvider;
 
-// @public
-export function sanitizeIdentifier(value: string): string;
-
-// @public
-export function sanitizeToolName(name: string): string;
-
-// @public
-export function serializePropertyName(name: string): string;
-
-// @public
-export interface ToolCall {
-    // (undocumented)
-    input: unknown;
-    // (undocumented)
-    providerName: string;
-    // (undocumented)
-    safeToolName: string;
-}
-
-// @public
-export type ToolCallResult = {
-    ok: true;
-    result: unknown;
-} | {
-    error: ExecuteError;
-    ok: false;
-};
-
 // @public
 export interface ToolDescriptor {
     description?: string;
@@ -193,7 +130,4 @@ export interface ToolProvider {
 // @public
 export type ToolSchema = JsonSchema | ZodTypeAny | ZodRawShape;
 
-// @public
-export type TypegenToolDescriptor = Pick<ResolvedToolDescriptor, "description" | "inputSchema" | "outputSchema"> & Partial<Pick<ResolvedToolDescriptor, "execute">>;
-
 ```

packages/core/src/index.ts

@@ -3,25 +3,9 @@
  * Public API for the `@execbox/core` package.
  */
 export type { Executor, ExecutorPoolOptions } from "./executor/executor";
-export {
-  assertValidIdentifier,
-  isReservedWord,
-  isValidIdentifier,
-  sanitizeIdentifier,
-  serializePropertyName,
-} from "./identifier";
-export { sanitizeToolName } from "./sanitize";
-export { ExecuteFailure, isExecuteFailure, isJsonSerializable } from "./errors";
+export { ExecuteFailure, isExecuteFailure } from "./errors";
 export { resolveProvider } from "./provider/resolveProvider";
-export { generateTypesFromJsonSchema } from "./typegen/jsonSchema";
-export type {
-  ExecutionOptions,
-  ExecutorRuntimeOptions,
-  ProviderManifest,
-  ProviderToolManifest,
-  ToolCall,
-  ToolCallResult,
-} from "./runner";
+export type { ExecutionOptions, ExecutorRuntimeOptions } from "./runner";
 export type {
   ExecuteError,
   ExecuteErrorCode,
@@ -33,5 +17,4 @@ export type {
   ToolExecutionContext,
   ToolProvider,
   ToolSchema,
-  TypegenToolDescriptor,
 } from "./types";

packages/quickjs/README.md

@@ -64,8 +64,6 @@ await executor.prewarm();
 
 ## Advanced Imports
 
-- `@execbox/quickjs/runner` exports the reusable QuickJS runner
-- `@execbox/quickjs/runner/protocol-endpoint` exports the low-level QuickJS protocol loop used by worker-hosted integrations
 - `@execbox/quickjs/remote-endpoint` adapts the QuickJS protocol loop to `@execbox/remote` runner ports
 
 ## Operational Notes

packages/quickjs/__tests__/entrypoints.test.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from "node:fs";
+
+import { describe, expect, it } from "vitest";
+
+import {
+  createEntrypointSpecifier,
+  workspaceEntrypoints,
+} from "../../../scripts/workspace-entrypoints.ts";
+
+interface PackageManifest {
+  exports: Record<string, unknown>;
+}
+
+function readPackageManifest(path: string): PackageManifest {
+  return JSON.parse(readFileSync(path, "utf8")) as PackageManifest;
+}
+
+describe("published entrypoints", () => {
+  it("keeps low-level QuickJS runner internals out of the public package surface", () => {
+    const manifest = readPackageManifest("packages/quickjs/package.json");
+    const specifiers = workspaceEntrypoints.map(createEntrypointSpecifier);
+
+    expect(manifest.exports).not.toHaveProperty("./runner");
+    expect(manifest.exports).not.toHaveProperty("./runner/protocol-endpoint");
+    expect(specifiers).not.toContain("@execbox/quickjs/runner");
+    expect(specifiers).not.toContain(
+      "@execbox/quickjs/runner/protocol-endpoint",
+    );
+  });
+});