[codex] Narrow public API surface

.changeset/narrow-public-api.md

@@ -0,0 +1,8 @@
+---
+"@anarchitecture/summon": minor
+"@anarchitecture/summon-server": minor
+"@anarchitecture/summon-react": minor
+---
+
+Narrow public package exports to explicit adoption-path APIs and move copied
+implementation output under `dist/_internal`.

.github/workflows/ci.yml

@@ -22,7 +22,23 @@ jobs:
         with:
           node-version: 22
           cache: pnpm
-      - run: pnpm install --frozen-lockfile
+      - name: Show package manager config
+        run: |
+          pnpm --version
+          pnpm config get registry
+      - name: Install dependencies
+        run: |
+          set +e
+          pnpm install --frozen-lockfile --reporter append-only 2>&1 | tee pnpm-install.log
+          status=${PIPESTATUS[0]}
+          if [ "$status" -ne 0 ]; then
+            echo "::group::pnpm install failure tail"
+            tail -120 pnpm-install.log
+            echo "::endgroup::"
+            message=$(tail -40 pnpm-install.log | sed -e 's/%/%25/g' -e 's/\r/%0D/g' -e ':a;N;$!ba;s/\n/%0A/g')
+            echo "::error title=pnpm install failed::$message"
+            exit "$status"
+          fi
       - run: pnpm typecheck
       - run: pnpm test
       - run: pnpm build
@@ -40,6 +56,22 @@ jobs:
         with:
           node-version: 22
           cache: pnpm
-      - run: pnpm install --frozen-lockfile
+      - name: Show package manager config
+        run: |
+          pnpm --version
+          pnpm config get registry
+      - name: Install dependencies
+        run: |
+          set +e
+          pnpm install --frozen-lockfile --reporter append-only 2>&1 | tee pnpm-install.log
+          status=${PIPESTATUS[0]}
+          if [ "$status" -ne 0 ]; then
+            echo "::group::pnpm install failure tail"
+            tail -120 pnpm-install.log
+            echo "::endgroup::"
+            message=$(tail -40 pnpm-install.log | sed -e 's/%/%25/g' -e 's/\r/%0D/g' -e ':a;N;$!ba;s/\n/%0A/g')
+            echo "::error title=pnpm install failed::$message"
+            exit "$status"
+          fi
       - run: pnpm exec playwright install --with-deps chromium webkit
       - run: pnpm test:safety

README.md

@@ -82,8 +82,9 @@ generation starts. The model sees that plan as a contract but cannot widen it.
 
 ## Public Packages
 
-- `@anarchitecture/summon` - core protocol, validation, surface plans, policy,
-  browser sandbox host, runtime assets, envelopes, and Devtools events.
+- `@anarchitecture/summon` - core protocol, surface plans, host contract
+  helpers, diagnostics primitives, and explicit browser/policy/envelope/assets/
+  Devtools subpaths.
 - `@anarchitecture/summon-server` - provider-neutral generation lifecycle,
   repair, summaries, and model-provider interfaces.
 - `@anarchitecture/summon-react` - `SummonSurface` and React component island

apps/demo/package.json

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@anarchitecture/summon": "workspace:*",
+    "@summon-internal/engine": "workspace:*",
     "zod": "^3.23.0"
   },
   "devDependencies": {

apps/demo/src/batch-main.ts

@@ -1,4 +1,5 @@
-import { spawnSandbox, PolicyEngine, type SandboxHandle } from '@anarchitecture/summon';
+import { spawnSandbox, type SandboxHandle } from '@anarchitecture/summon/browser';
+import { PolicyEngine } from '@anarchitecture/summon/policy';
 import {
   parseProtocolLine,
   SectionAccumulator,

apps/demo/src/capabilities.ts

@@ -13,8 +13,8 @@ import {
   defineWorkerResource,
   type CapabilityDefinition,
   type CapabilityRegistry,
-  type IntentHandler,
 } from '@anarchitecture/summon';
+import type { IntentHandler } from '@anarchitecture/summon/policy';
 import { z } from 'zod';
 
 const logArgsSchema = z.object({ payload: z.any().optional() }).passthrough();

apps/demo/src/generate-main.ts

@@ -1,20 +1,21 @@
 import {
+  type ComponentIslandRegistry,
+  type SurfaceStreamContext,
+  type SurfaceStreamResult,
   consumeSurfaceStream,
   createComponentIslandRegistry,
   spawnSandbox,
-  PolicyEngine,
+  type SandboxHandle,
+} from '@anarchitecture/summon/browser';
+import {
   createSurfaceEnvelope,
   parseSurfaceEnvelope,
-  type SandboxHandle,
-  type ComponentIslandRegistry,
-  type SurfaceStreamContext,
-  type SurfaceStreamResult,
   type SurfaceEnvelope,
-} from '@anarchitecture/summon';
+} from '@anarchitecture/summon/envelope';
+import { PolicyEngine } from '@anarchitecture/summon/policy';
 import {
   deriveSurfacePlanControls,
   normalizeSurfacePlan,
-  parseTokenValues,
   SectionAccumulator,
   SURFACE_AUTHORITY_VALUES,
   SURFACE_DATA_VALUES,
@@ -31,6 +32,7 @@ import {
   type ValidationCapability,
   type ValidationComponent,
 } from '@anarchitecture/summon';
+import { parseTokenValues } from '@summon-internal/engine';
 import { createEventStore, type DevtoolsEvent } from '@anarchitecture/summon/devtools';
 import bootstrapSource from '@anarchitecture/summon/bootstrap.js?raw';
 import defaultTokensSource from '@anarchitecture/summon/tokens.css?raw';

apps/demo/src/main.ts

@@ -1,4 +1,4 @@
-import { spawnSandbox } from '@anarchitecture/summon';
+import { spawnSandbox } from '@anarchitecture/summon/browser';
 import bootstrapSource from '@anarchitecture/summon/bootstrap.js?raw';
 import tokensSource from '@anarchitecture/summon/tokens.css?raw';
 import { ADVERSARIAL_BODY_HTML } from './adversarial-artifact.js';

apps/demo/src/strict-main.ts

@@ -10,11 +10,11 @@
  */
 import {
   spawnSandbox,
-  PolicyEngine,
   createStrictInputRegistry,
   type SandboxHandle,
   type StrictInputController,
-} from '@anarchitecture/summon';
+} from '@anarchitecture/summon/browser';
+import { PolicyEngine } from '@anarchitecture/summon/policy';
 import bootstrapSource from '@anarchitecture/summon/bootstrap.js?raw';
 import tokensSource from '@anarchitecture/summon/tokens.css?raw';
 import { STRICT_DEMO_BODY_HTML } from './strict-demo-artifact.js';

apps/server/package.json

@@ -15,7 +15,8 @@
     "cors": "^2.8.5",
     "express": "^4.21.2",
     "@anarchitecture/summon": "workspace:*",
-    "@anarchitecture/summon-server": "workspace:*"
+    "@anarchitecture/summon-server": "workspace:*",
+    "@summon-internal/engine": "workspace:*"
   },
   "devDependencies": {
     "@types/cors": "^2.8.17",

apps/server/src/directions-loader.ts

@@ -5,7 +5,7 @@ import {
   compileDirectionContract,
   coerceOpts,
   type DirectionOpts,
-} from '@anarchitecture/summon';
+} from '@summon-internal/engine';
 
 export const PREFERRED_DEFAULT_DIRECTION_ID = 'ghost';
 

apps/server/src/ghost-adapter.ts

@@ -8,7 +8,8 @@ import {
   type GhostMemoryStackLayer,
   type PackageMemory,
 } from '@anarchitecture/ghost/scan';
-import { compileTokenContract, type ProtocolLine } from '@anarchitecture/summon';
+import type { ProtocolLine } from '@anarchitecture/summon';
+import { compileTokenContract } from '@summon-internal/engine';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';

apps/server/src/main.ts

@@ -2,14 +2,14 @@ import express from 'express';
 import cors from 'cors';
 import Anthropic from '@anthropic-ai/sdk';
 import {
-  parseTokenValues,
   type CapabilityPack,
   type ContractPromptBlock,
   type ProtocolLine,
   type ScriptPolicy,
   type SummonLayout,
   type TokenOverride,
 } from '@anarchitecture/summon';
+import { parseTokenValues } from '@summon-internal/engine';
 import {
   resolveSurfaceGenerationPlan,
   runSurfaceGeneration,

docs/adoption/integration.md

@@ -213,10 +213,10 @@ not from the artifact.
 ```ts
 import {
   createComponentIslandRegistry,
-  PolicyEngine,
   spawnSandbox,
   type SandboxHandle,
-} from '@anarchitecture/summon';
+} from '@anarchitecture/summon/browser';
+import { PolicyEngine } from '@anarchitecture/summon/policy';
 import {
   bootstrapSource,
   tokensSource,

docs/adoption/public-packaging.md

@@ -14,11 +14,11 @@ Publish by install environment, not by internal implementation layer.
 @anarchitecture/summon-react
 ```
 
-`@anarchitecture/summon` is the frameworkless client/core package. It owns the
-browser-facing runtime contract: protocol types and parsers, surface envelopes,
-capability registry helpers, `PolicyEngine`, stream consumption,
-`spawnSandbox`, runtime assets, validation helpers, and Devtools event store
-exports.
+`@anarchitecture/summon` is the shared host/contract package. Its root export is
+kept narrow: protocol parsing, surface-plan helpers, host capability/component
+contract helpers, and public diagnostics types. Browser runtime, policy,
+envelope, assets, and Devtools APIs live on explicit subpaths such as
+`@anarchitecture/summon/browser` and `@anarchitecture/summon/policy`.
 
 `@anarchitecture/summon-server` is the provider-neutral generation package. It
 owns `runSurfaceGeneration`, prompt/contract assembly, repair feedback, summary
@@ -73,9 +73,11 @@ Keep the private implementation graph boring:
 - Keep docs/examples on public package names.
 - Publish only `@anarchitecture/summon`, `@anarchitecture/summon-server`, and
   `@anarchitecture/summon-react`.
-- Build public packages by copying implementation `dist` output and rewriting
-  private imports to public or relative imports.
-- Fail CI if public JS or `.d.ts` imports `@summon-internal/*`.
+- Build public packages by copying implementation `dist` output under
+  `dist/_internal/*` and writing explicit public wrapper files.
+- Fail CI if public JS or `.d.ts` imports `@summon-internal/*`, public wrappers
+  use `export *`, public-looking implementation dirs appear at `dist/*`, or
+  wrapper exports drift from `scripts/public-api-manifest.json`.
 - Do source-health work here when it is destination-agnostic: tests, security
   fixes, API cleanup, build reliability, and package metadata correctness.
 

package.json

@@ -7,10 +7,12 @@
     "dev": "pnpm --filter @summon-internal/demo dev",
     "dev:server": "pnpm --filter @summon-internal/demo-server dev",
     "dev:all": "pnpm -r --parallel --stream --filter @summon-internal/demo-server --filter @summon-internal/demo dev",
-    "build:impl": "pnpm -r --filter @summon-internal/devtools --filter @summon-internal/engine --filter @summon-internal/sandbox-runtime --filter @summon-internal/host --filter @summon-internal/server --filter @summon-internal/react build",
+    "build:impl": "pnpm -r --filter @summon-internal/devtools --filter @summon-internal/engine --filter @summon-internal/sandbox-runtime --filter @summon-internal/host --filter @summon-internal/server build",
+    "build:react-impl": "pnpm --filter @summon-internal/react build",
+    "build:public-core": "node scripts/build-public-packages.mjs summon summon-server",
     "build:public": "node scripts/build-public-packages.mjs",
     "build:apps": "pnpm --filter @summon-internal/demo build",
-    "build": "pnpm build:impl && pnpm build:public && pnpm build:apps",
+    "build": "pnpm build:impl && pnpm build:public-core && pnpm build:react-impl && pnpm build:public && pnpm build:apps",
     "check:public-packages": "node scripts/check-public-packages.mjs",
     "pack:dry-run": "pnpm -r --filter \"@anarchitecture/*\" exec npm --cache /tmp/summon-npm-cache pack --dry-run --json",
     "smoke:public-packages": "node scripts/smoke-public-packages.mjs",
@@ -24,7 +26,7 @@
     "port-direction": "tsx scripts/port-direction.ts",
     "eval-directions": "tsx scripts/eval-directions.ts"
   },
-  "packageManager": "pnpm@10.0.0",
+  "packageManager": "pnpm@10.33.0",
   "engines": {
     "node": ">=18"
   },

packages/devtools/src/index.ts

@@ -17,5 +17,8 @@ export type {
   ProtocolParseErrorEvent,
   StreamLifecycleEvent,
   StreamGraphEvent,
+  SurfacePlanEvent,
   RenderEvent,
+  ComponentSyncEvent,
+  ComponentErrorEvent,
 } from './types.js';

packages/react/package.json

@@ -19,10 +19,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@summon-internal/devtools": "workspace:*",
-    "@summon-internal/engine": "workspace:*",
-    "@summon-internal/host": "workspace:*",
-    "@summon-internal/sandbox-runtime": "workspace:*"
+    "@anarchitecture/summon": "workspace:*"
   },
   "peerDependencies": {
     "react": ">=18.3.0 || >=19.0.0",

packages/react/src/index.ts

@@ -1,23 +1,25 @@
-import { createEventStore, type DevtoolsEvent, type EventStore } from '@summon-internal/devtools';
-import { SectionAccumulator, type ProtocolLine } from '@summon-internal/engine';
+import {
+  type CapabilityRegistry,
+  type ComponentDefinition,
+  type ComponentRegistry,
+  SectionAccumulator,
+  type ProtocolLine,
+} from '@anarchitecture/summon';
 import {
   createComponentIslandRegistry,
-  defineComponent as defineHostComponent,
-  PolicyEngine,
   spawnSandbox,
   type Artifact,
-  type CapabilityRegistry,
-  type ComponentDefinition,
   type ComponentIslandError,
   type ComponentIslandRegistry,
-  type ComponentRegistry,
   type SandboxHandle,
-} from '@summon-internal/host';
-import type { SurfaceEnvelope } from '@summon-internal/host/envelope';
+} from '@anarchitecture/summon/browser';
+import { createEventStore, type DevtoolsEvent } from '@anarchitecture/summon/devtools';
+import type { SurfaceEnvelope } from '@anarchitecture/summon/envelope';
+import { PolicyEngine } from '@anarchitecture/summon/policy';
 import {
   bootstrapSource as defaultBootstrapSource,
   tokensSource as defaultTokensSource,
-} from '@summon-internal/sandbox-runtime/assets';
+} from '@anarchitecture/summon/assets';
 import { createElement, useEffect, useMemo, useRef, type ComponentType, type CSSProperties } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 
@@ -193,7 +195,7 @@ export function defineReactComponent<T, P = T>(
 ): ComponentDefinition<T> {
   const roots = new WeakMap<HTMLElement, Root>();
   const { component, mapProps, ...rest } = definition;
-  return defineHostComponent({
+  return {
     ...rest,
     render: ({ container, props, componentId, sandboxId, emitIntent }) => {
       let root = roots.get(container);
@@ -215,7 +217,7 @@ export function defineReactComponent<T, P = T>(
       root?.unmount();
       roots.delete(container);
     },
-  });
+  };
 }
 
 function resolveHtml(props: SummonSurfaceProps): string {

packages/react/tsconfig.build.json

@@ -6,10 +6,18 @@
     "noEmit": false,
     "outDir": "./dist",
     "paths": {
+      "@anarchitecture/summon": ["packages/summon/dist/index.d.ts"],
+      "@anarchitecture/summon/assets": ["packages/summon/dist/assets.d.ts"],
+      "@anarchitecture/summon/browser": ["packages/summon/dist/browser.d.ts"],
+      "@anarchitecture/summon/devtools": ["packages/summon/dist/devtools.d.ts"],
+      "@anarchitecture/summon/envelope": ["packages/summon/dist/envelope.d.ts"],
+      "@anarchitecture/summon/policy": ["packages/summon/dist/policy.d.ts"],
       "@summon-internal/devtools": ["packages/devtools/dist/index.d.ts"],
       "@summon-internal/engine": ["packages/engine/dist/index.d.ts"],
       "@summon-internal/host": ["packages/host/dist/index.d.ts"],
+      "@summon-internal/host/browser": ["packages/host/dist/browser.d.ts"],
       "@summon-internal/host/envelope": ["packages/host/dist/envelope.d.ts"],
+      "@summon-internal/host/policy": ["packages/host/dist/policy.d.ts"],
       "@summon-internal/sandbox-runtime/assets": ["packages/sandbox-runtime/dist/assets.d.ts"]
     },
     "rootDir": "./src",

packages/summon-react/src/index.ts

@@ -1 +1,10 @@
-export * from '@summon-internal/react';
+export {
+  SummonSurface,
+  defineReactComponent,
+} from '@summon-internal/react';
+export type {
+  ReactComponentRuntimeContext,
+  ReactComponentWithRuntimeDefinition,
+  SummonSurfaceChrome,
+  SummonSurfaceProps,
+} from '@summon-internal/react';