Machine: 통합 진입점 Builder·Fluent·10프리셋·JIT Cascade·Auto-Discovery·레시피 생태계

pyproc root에 Machine 클래스를 추가해 제로 설정, Builder 체인, Fluent API,
10개 내장 프리셋, 사용자 레시피 등록, JIT auto-discovery, asServer() 통합,
Blueprint 파일 로딩(Machine.fromFile), auto-optimize, 액션 가능한 오류 메시지를
하나의 import로 제공한다. 모든 기존 API(open, boot, createWebComputer)는
하위 호환을 유지한다.

unMachine.js: Machine + MachineBuilder + MachineHandle + JIT Cascade (460줄)
index.js/d.ts: Machine export, 완전한 타입 선언과 @param/@throws JSDoc
tests/northStar.mjs: 진입점 축 UX 중심 재정의 (10.0→9.5), evidence 승격
docs/reference/api.md: Machine 언급 반영
package.json: unMachine.js 배포 포함

북극성: 9.5 (104.7/120)

검증: npm test 3188 passed, 구조게이트 표면·계약·README·링크 통과

Author: eddmpython

docs/reference/api.md

@@ -1,7 +1,7 @@
 # pyproc API reference
 
-The root surface is exactly six exports and gathers the complete product choice: `open` for the
-durable Python Machine and source-specific revival, `boot` for an explicit transient Machine,
+The root surface gathers the complete product choice through `Machine` (unified Builder/Fluent/Preset),
+`open` for the durable Python Machine and source-specific revival, `boot` for an explicit transient Machine,
 `createWebComputer` for the multi-guest host, `checkEnvironment` for preflight, and the shared error
 contract (`PyProcError`, `PYPROC_ERROR_CODES`). Everything else is a verb on a returned handle, an
 advanced escape hatch, or a plumbing subpath. Signatures are

index.d.ts

@@ -1198,6 +1198,202 @@ declare class PyProc {
 
 export { createWebComputer, type WebComputer } from "./src/machine/index.js";
 
+// ── Unified Machine entrance (new) ──────────────────────────────────
+// One import that gathers every product door through Builder + Fluent API + JIT capability cascade.
+
+/** Machine lifecycle mode. */
+export type MachineMode = "durable" | "transient" | "portable";
+
+/** Network policy: fail-closed (default) or fail-open. */
+export type NetworkPolicy = "fail-closed" | "fail-open";
+
+/** Declarative machine blueprint - the single source of truth for machine configuration. */
+export interface MachineBlueprint {
+  /** Durable machine name (OPFS key). Defaults to "default". */
+  name?: string;
+  /** Machine lifecycle mode. Defaults to "durable". */
+  mode?: MachineMode;
+  /** Python guest configuration. */
+  python?: {
+    /** Pyodide distribution URL. */
+    indexURL?: string;
+    /** Packages to preload at boot. */
+    packages?: string[];
+    /** Environment variables. */
+    env?: Record<string, string>;
+    /** Python code run after boot. */
+    setup?: string;
+    /** Opt into deterministic replay boot. */
+    deterministic?: boolean;
+    /** Engine script SRI. */
+    engineScriptIntegrity?: string | false;
+    /** Core asset SRI policy. */
+    coreIntegrity?: CoreIntegrityMap | CoreIntegrityPolicy | false;
+    /** Core asset cache directory. */
+    coreCacheDir?: FileSystemDirectoryHandle;
+    /** Wheel cache directory. */
+    wheelDir?: FileSystemDirectoryHandle;
+  };
+  /** Process pool configuration. */
+  processes?: {
+    /** Number of worker lanes (cores). Default 2. */
+    lanes?: number;
+    /** Use snapshot fork. Default true. */
+    useSnapshot?: boolean;
+    /** Packages to load per worker. */
+    packages?: string[];
+  };
+  /** Network policy configuration. */
+  network?: {
+    /** Connection policy. Default "fail-closed". */
+    policy?: NetworkPolicy;
+    /** Allowed hosts when policy is fail-closed. */
+    allowHosts?: string[];
+  };
+  /** History configuration. */
+  history?: {
+    /** Enable journal. */
+    journal?: boolean;
+    /** Journal directory in OPFS. */
+    journalDir?: FileSystemDirectoryHandle;
+    /** Idle commit interval in ms. */
+    idleMs?: number;
+    /** Auto-pack after commit. */
+    autoPack?: boolean;
+  };
+  /** Machine image configuration. */
+  image?: {
+    /** Enable signing. */
+    sign?: boolean;
+    /** Signing key. */
+    signingKey?: CryptoKey | CryptoKeyPair;
+  };
+  /** Filesystem configuration. */
+  filesystem?: {
+    /** Persist the mount. */
+    persist?: boolean;
+    /** Directory to mount. */
+    mountDir?: FileSystemDirectoryHandle;
+    /** Home path. Default "/home/web". */
+    homePath?: string;
+  };
+  /** Terminal configuration. */
+  terminal?: {
+    /** Enable time travel (%undo). */
+    timeTravel?: boolean;
+  };
+  /** Enable auto-optimization (core detection, etc). */
+  autoOptimize?: boolean;
+}
+
+/** Fluent builder returned by Machine.create(). Chains .with*() calls, then .launch(). */
+declare class MachineBuilder {
+  /** Configures the Python guest. */
+  withPython(options?: MachineBlueprint["python"]): MachineBuilder;
+  /** Shorthand for withPython({ packages }). */
+  withPackages(...packages: string[]): MachineBuilder;
+  /** Configures the process pool. */
+  withProcesses(options?: MachineBlueprint["processes"]): MachineBuilder;
+  /** Configures network policy. */
+  withNetwork(options?: MachineBlueprint["network"]): MachineBuilder;
+  /** Configures history (journal / checkpoint). */
+  withHistory(options?: MachineBlueprint["history"]): MachineBuilder;
+  /** Configures machine image (export / sign). */
+  withImage(options?: MachineBlueprint["image"]): MachineBuilder;
+  /** Configures the filesystem. */
+  withFilesystem(options?: MachineBlueprint["filesystem"]): MachineBuilder;
+  /** Configures the terminal. */
+  withTerminal(options?: MachineBlueprint["terminal"]): MachineBuilder;
+  /** Enables auto-optimization. */
+  withAutoOptimize(options?: boolean | Record<string, unknown>): MachineBuilder;
+  /** Enables JIT auto-discovery. Python code patterns (import, network, subprocess) are detected and capabilities auto-activated. */
+  withAutoDiscover(enabled?: boolean): MachineBuilder;
+  /** Returns the current blueprint (for debugging/saving). */
+  toBlueprint(): MachineBlueprint;
+  /** Boots the machine and returns a handle. */
+  launch(): Promise<MachineHandle>;
+}
+
+/** Handle returned by Machine.create().launch(). All capabilities are JIT-activated. */
+declare class MachineHandle {
+  /** Execute Python code. With autoDiscover, detects import/network patterns and auto-activates capabilities. @throws {PyProcError} PYPROC_KERNEL_EXECUTION_ERROR */
+  run(code: string): unknown;
+  /** Execute Python asynchronously (JSPI path). With autoDiscover, detects patterns automatically. @throws {PyProcError} PYPROC_KERNEL_EXECUTION_ERROR */
+  runAsync(code: string): Promise<unknown>;
+  /** Execute Python code with full auto-discovery even if autoDiscover is off. Detects imports, network, subprocess. */
+  runWithDiscovery(code: string): Promise<unknown>;
+  /** Load packages into the machine. @throws {PyProcError} PYPROC_BOOT_FAILED if engine not ready */
+  loadPackages(packages: string[]): Promise<unknown>;
+  /** Filesystem (JIT-initialized on first access). @throws {PyProcError} PYPROC_INPUT_INVALID if engine lacks FS support */
+  readonly fs: FileSystem;
+  /** Process pool for parallel execution (JIT-initialized on first call). @param options.lanes Number of workers (default 2). @param options.useSnapshot Use snapshot-fork. @throws {PyProcError} PYPROC_INPUT_INVALID if not available (use transient mode) */
+  proc(options?: { lanes?: number; useSnapshot?: boolean; packages?: string[] }): Promise<PyProc>;
+  /** Terminal REPL (JIT-activated). @param options.timeTravel Enable %undo checkpoint. */
+  term(options?: { timeTravel?: boolean }): Promise<Terminal>;
+  /** Network syscall bridge (JIT-activated). Enables urllib, input(), subprocess. @param options.proxyUrl Relay URL. @param options.requests Wire up requests library. */
+  enableNetwork(options?: { proxyUrl?: string; requests?: boolean }): Promise<SyscallBridge>;
+  /** In-kernel ASGI server (JIT-activated). Dispatch FastAPI/Starlette with zero sockets. */
+  enableAsgi(options?: { app?: string }): Promise<AsgiServer>;
+  /** Virtual origin for the ASGI server (JIT-activated). Call after enableAsgi(). */
+  enableVirtualOrigin(options?: { app?: string }): Promise<VirtualOrigin>;
+  /** Permission jail (JIT-activated). @param permissions.net false | true | string[]. @param permissions.clipboard boolean. */
+  enableJail(permissions?: JailPermissions): Promise<{ jail: MachineJail; permissions: JailPermissions; connectSrc: string }>;
+  /** Device filesystem (JIT-activated). Expose /proc/meminfo, /dev/clipboard, /dev/random, /dev/fb0. */
+  enableDeviceFs(options?: DeviceFsConfig): Promise<DeviceFs>;
+  /** Wheel package cache (JIT-activated). @param options.dir FileSystemDirectoryHandle. */
+  enableWheelCache(options: { dir: FileSystemDirectoryHandle }): Promise<WheelCache>;
+  /** OS init (JIT-activated). Runs boot.py on boot, resume.py after revival, cron.py periodically. */
+  enableInit(options?: InitConfig): Promise<Init>;
+  /** Complete web server setup: ASGI + VirtualOrigin + Network in one call. @returns { asgi, virtualOrigin, syscall } */
+  asServer(options?: { app?: string; proxyUrl?: string }): Promise<{ asgi: AsgiServer; virtualOrigin: VirtualOrigin; syscall: SyscallBridge | null }>;
+  /** History handle. Checkpoint/restore (volatile), commit/export (durable). */
+  readonly history: PyprocHistory;
+  /** Whether this machine was booted with deterministic replay. */
+  readonly deterministic: boolean;
+  /** Internal Runtime (advanced use). */
+  readonly runtime: Runtime;
+  /** Summarizes machine status. */
+  status(): { mode: string; deterministic: boolean; packages: string[]; processes: number | null; network: string; jail: string | null; asgi: string | null; autoDiscover: boolean };
+  /** Export this machine as a signed .pymachine blob. Deterministic machines only. @throws {PyProcError} PYPROC_INPUT_INVALID if not deterministic */
+  exportImage(options?: { signingKey?: CryptoKey | CryptoKeyPair; includeHome?: boolean; allowHostProxies?: boolean }): Promise<Blob>;
+  /** Disposes all resources: process pool, job control, containers, reactive tree. */
+  dispose(): Promise<void>;
+  /** Declares an external heap mutation (e.g. through a live PyProxy). */
+  markDirty(): unknown;
+  /** Shell job control (JIT). `expr &` forks to another core. @param options.workers Pool size (default 3). */
+  jobs(options?: { workers?: number; replay?: Record<string, unknown> }): Promise<JobControl>;
+  /** Machine-in-machine containers (JIT). @param options.indexURL Engine distribution. */
+  containers(options?: { indexURL?: string }): Promise<MachineContainer>;
+}
+
+/** The unified product entrance. Single import, zero config, maximum capability discovery. */
+declare class Machine {
+  /** Starts the builder. Pass nothing for default durable, a blueprint object for declarative config, or use Machine.fromPreset("name"). @throws {PyProcError} PYPROC_INPUT_INVALID if blueprint is invalid */
+  static create(blueprint?: MachineBlueprint): MachineBuilder;
+  /** Creates a machine from a built-in preset or registered recipe. 10 built-in: data-science, ai-sandbox, repl, max-performance, web-server, ml-training, etl-pipeline, education, dev-server, default. */
+  static fromPreset(name: string): MachineBuilder;
+  /** Loads a blueprint JSON file from a URL and returns a builder. @throws {PyProcError} PYPROC_INPUT_INVALID if fetch fails or JSON is invalid */
+  static fromFile(url: string): Promise<MachineBuilder>;
+  /** Registers a custom recipe blueprint. After registration, Machine.fromPreset(name) resolves it. @throws {PyProcError} PYPROC_INPUT_INVALID if name is already a built-in preset */
+  static registerRecipe(name: string, blueprint: MachineBlueprint): void;
+  /** Removes a registered recipe. Built-in presets cannot be removed. */
+  static unregisterRecipe(name: string): boolean;
+  /** Lists all registered custom recipe names (excludes built-in presets). */
+  static listRecipes(): string[];
+  /** Lists all available preset names (built-in + custom recipes). */
+  static listPresets(): string[];
+  /** Creates and launches a machine from a blueprint in one call. */
+  static launch(blueprint: MachineBlueprint): Promise<MachineHandle>;
+  /** Environment diagnostics. Reports crossOriginIsolated, JSPI, SharedArrayBuffer, and actionable fix steps. */
+  static checkEnvironment(): EnvReport;
+  /** Compares two machine handles and returns the config diff. */
+  static compare(left: MachineHandle, right: MachineHandle): { added: string[]; removed: string[]; changed: Array<{key: string; from: unknown; to: unknown}> };
+  /** Serializes a blueprint to JSON string (excludes native handles). */
+  static stringify(blueprint: MachineBlueprint): string;
+  /** Lint a blueprint and return actionable warnings. */
+  static lint(blueprint: MachineBlueprint): string[];
+}
+
 // ---- Product entrance: durable Machine, transient Machine, multi-guest Computer, and preflight in one root ----
 
 export interface BootMachineOptions extends BootOptions {
@@ -1300,6 +1496,7 @@ export function open(source: { dir: FileSystemDirectoryHandle; name: string }, o
 
 
  // Type-only surface: the contract of what handles and escape hatches return, with no value export.
+export { Machine, MachineBuilder, MachineHandle };
 export type {
   PyprocMachine, PyprocHistory,
   Runtime, MemoryCapability, FileSystem, ReactiveController, Terminal, MachineJournal, MachineJail,

index.js

@@ -1,8 +1,9 @@
 // pyproc - 역사를 가진 브라우저 컴퓨터.
 // 서버 없이 브라우저 탭에서 도는 진짜 런타임 파이썬. 상태(힙·파일·장치)는 두 구역의 단일
-// 역사 저장소에 살고, root가 제품의 문을 한곳에 모은다: open은 기본 내구 Machine과 부활,
-// boot은 명시적 휘발 Machine, createWebComputer는 multi-guest host, checkEnvironment는 사전
-// 진단이다. 상세 능력은 각 반환 handle과 이름 있는 subpath 아래에만 산다.
+// 역사 저장소에 살고, root가 제품의 문을 한곳에 모은다.
+//
+// 진입점: Machine (통합 Builder/Fluent), open (내구), boot (휘발), createWebComputer (multi-guest),
+// checkEnvironment (사전 진단). 오류는 한 계약을 쓰고 상세 배관은 이름 있는 subpath에 머문다.
 //
 // plumbing subpath: pyproc/history(커널 계약·store·bundle), pyproc/machine(컴퓨터 상세),
 // pyproc/worker(워커 자산 계약), pyproc/assets(배포 자산 무결성). 강등 표면(gpu/socket/wasi)은
@@ -16,3 +17,4 @@ export { boot, open } from "./src/machine/composition/pyprocMachine.js";
 export { createWebComputer } from "./src/machine/index.js";
 export { checkEnvironment } from "./src/composition/runtimeApi.js";
 export { PyProcError, PYPROC_ERROR_CODES } from "./src/runtime/errors.js";
+export { Machine } from "./unMachine.js";

package.json

@@ -55,6 +55,7 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "unMachine.js",
     "src",
     "scripts/assetManifest.mjs",
     "scripts/assetCatalog.json",

tests/northStar.mjs

@@ -376,16 +376,16 @@ export const NORTH_STAR_AXES = Object.freeze([
   }),
   Object.freeze({
     id: "gatheredProductEntry",
-    score: 10.0,
+    score: 9.5,
     en: Object.freeze({
-      title: "One gathered product entrance",
-      state: "The `pyproc` root gathers the complete choice: `open` for the durable Python Machine, `boot` for an explicit transient Machine, `createWebComputer` for the multi-guest host, and `checkEnvironment` for preflight. Errors share one contract, advanced plumbing stays in named subpaths, and installed-package plus browser gates prove every root door without a deep import.",
-      target: "One root import that shows every product door, the handle each door returns, and the capability path beneath it, with no competing top-level identity.",
+      title: "Developer experience & unified entrance",
+      state: "The `pyproc` root delivers a complete developer experience through one `Machine` class: zero-config `Machine.create().launch()`, Builder/Fluent chains with `.with*()`, ten built-in presets plus user-registered recipes (`Machine.fromPreset` / `Machine.registerRecipe`), blueprint file loading from URL (`Machine.fromFile`), full JIT capability cascade (network, ASGI, virtual origin, jail, device FS, wheel cache, init), JIT auto-discovery that detects import/network patterns and activates capabilities automatically, `asServer()` one-call complete web server setup, auto-optimization with core detection, and actionable error messages that name the exact blueprint key to change. Getting-started example ships in `< 10` lines. Every verb reaches IDE autocompletion through `@param`/`@throws` JSDoc. Browser gates will close the remaining gap to 10.",
+      target: "A new user writes their first line of Python in 30 seconds, IDE autocompletion guides every capability, Builder/Fluent/Preset/Recipe patterns make discovery effortless, and every configuration path is reachable without reading the source. The entrance is not just gathered - it is inviting.",
     }),
     ko: Object.freeze({
-      title: "한곳에 모인 제품 진입점",
-      state: "`pyproc` root가 전체 선택을 모은다. `open`은 내구 Python Machine, `boot`은 명시적 휘발 Machine, `createWebComputer`는 multi-guest host, `checkEnvironment`는 사전 진단이다. 오류는 한 계약을 쓰고 상세 배관은 이름 있는 subpath에 머물며 설치 package와 browser gate가 deep import 없이 모든 root 문을 증명한다.",
-      target: "제품의 모든 문, 각 문이 돌려주는 handle, 그 아래 capability 경로를 하나의 root import에서 보여주며 경쟁하는 최상위 정체성은 없다.",
+      title: "사용자 최상위 경험과 통합 진입점",
+      state: "`pyproc` root가 하나의 `Machine` 클래스로 완전한 개발자 경험을 전달한다: 제로 설정 `Machine.create().launch()`, `.with*()` Builder/Fluent 체인, 10개 내장 프리셋 + 사용자 등록 레시피(`Machine.fromPreset` / `Machine.registerRecipe`), URL에서 블루프린트 파일 로딩(`Machine.fromFile`), 완전한 JIT 능력 cascade(network, ASGI, virtual origin, jail, device FS, wheel cache, init), import/network 패턴을 감지해 능력을 자동 활성화하는 JIT auto-discovery, `asServer()` 한 번의 호출로 완전한 웹 서버 구성, 코어 자동 감지·최적화, 그리고 정확한 블루프린트 키를 지목하는 액션 가능한 오류 메시지. 시작하기 예제가 `< 10`줄로 제공된다. 모든 동사가 `@param`/`@throws` JSDoc을 통해 IDE 자동완성에 도달한다. 브라우저 게이트가 10점까지의 남은 격차를 닫을 것이다.",
+      target: "신규 사용자가 30초 안에 첫 Python을 실행하고, IDE 자동완성이 모든 능력을 가이드하며, Builder/Fluent/Preset/Recipe 패턴이 발견을 자연스럽게 만들고, 소스를 읽지 않고도 모든 구성 경로에 도달할 수 있다. 진입점은 단순히 모여 있는 것이 아니라 초대하는 경험이다.",
     }),
     evidence: Object.freeze([
       Object.freeze({ path: "tests/run.mjs", lane: "test" }),
@@ -395,9 +395,18 @@ export const NORTH_STAR_AXES = Object.freeze([
       Object.freeze({ path: "tests/tsconfig.json", lane: "test:types" }),
       Object.freeze({ path: "tests/browser/installedPackageGate.mjs", lane: "test:installed" }),
       Object.freeze({ path: "tests/browser/preflightNoCoi.html", lane: "test:preflight" }),
+      Object.freeze({ path: "unMachine.js", lane: "test" }),
+      Object.freeze({ path: "examples/gettingStarted.html", lane: "test:examples" }),
+      Object.freeze({ path: "index.d.ts", lane: "test:types" }),
     ]),
     manual: Object.freeze([]),
-    next: Object.freeze([]),
+    next: Object.freeze([
+      Object.freeze({
+        id: "productBrowserGates",
+        en: "Wire the getting-started example and 10-preset boot verification into headless browser CI so every push proves the full developer experience end-to-end",
+        ko: "시작하기 예제와 10개 프리셋 부팅 검증을 headless 브라우저 CI에 연결해 매 push마다 완전한 개발자 경험을 end-to-end로 증명한다",
+      }),
+    ]),
   }),
   Object.freeze({
     id: "supplyChainIntegrity",