이 문서는 제품이 pyproc의 어떤 능력을 믿고 쓸 수 있는지 판단하기 위한 표다. 구현 지도나 설치 규칙이 아니며, 공개 표면을 제품 가치, 현재 상태, 필수 조건, 실행 표면, 검증, 경계로 묶는다.
정본 역할은 나뉜다.
- 설치, 버전 핀, import 경계: contract.md
- 속도 실측 계약: benchmarking.md (측정치는 원장과 artifact에만 산다. 속도는 Speed Lab으로 각자 재는 것이지 여기 걸린 숫자를 믿는 것이 아니다)
.pymachine신뢰와 권한 UI: trustPermissions.md- 이동 bundle(
PYBUNDLE1) 봉투 레이아웃: bundleFormat.md - 부활 뒤 제품 자원 재개설: resumeCatalog.md
상태 라벨은 README의 Feature status와 맞춘다. Stable은 기본 제품 경로로 둘 수 있는 표면, Beta는 제품에 붙일 수 있으나 브라우저 조건과 fallback을 함께 둬야 하는 표면, Experimental은 명시적 제품 선택과 관측이 필요한 표면, Research preview는 엔진 가능성 검증 표면이다.
| 라벨 | 승격 조건(전부 충족) |
|---|---|
| Stable | (a) CI 런타임 게이트가 실동작을 커버한다. (b) 마지막 브레이킹 변경 이후 릴리즈가 1개 이상 지났다(표면 동결 증거). (c) 30일 soak(그 사이 게이트 연속 GREEN). (d) 경계(안 되는 것)가 이 표와 레퍼런스에 문서화되어 있다. |
| Beta | (a)와 (d). 브라우저 조건/fallback 요구가 표에 명시된다. |
| Experimental | 실행 표면과 검증 명령이 존재한다(수동 probe 허용). |
| Research preview | 실증 장치로서의 정체와 프로덕션 정본이 무엇인지 명시된다. |
강등은 즉시다: 게이트가 빠지거나 브레이킹이 들어오면 라벨을 내리는 데 조건이 없다.
Stable 라벨을 단 행과 그 근거를 여기 기록한다. 이 원장에 없는 Stable 행은 구조 게이트가 차단한다(문서 근거 없는 라벨 상승 = 드리프트).
| 표면 | Stable 판정일 | 근거 |
|---|---|---|
Python runtime (boot/run/loadPackages) |
2026-07-15 이전 | (a) browser gate 상시, (b) 0.0.x 다수 릴리즈 표면 동결, (c) 장기 soak(게이트 연속 GREEN), (d) 문서화 |
| Deployment asset integrity | 2026-07-15 이전 | (a) browser + 설치 tarball 게이트, (b) 릴리즈 경과, (c) 장기 soak(게이트 연속 GREEN), (d) 문서화 |
승격 대기 시계: reactive(체크포인트/복원), session(.pymachine), machineJournal은 v0.0.10(브레이킹 묶음 릴리즈)이 (b)의 기준점이다. 다음 릴리즈 시점에 (a)(c)(d)와 함께 재판정한다. 지금 올리지 않는 것이 정직이다: 방금 표면이 바뀐 레인을 Stable이라 부르면 라벨의 의미가 죽는다.
실행 표면은 사람이 여는 예제, 브라우저 게이트, probe, 또는 tracked benchmark artifact다. 제품 claim은 아래 표의 실행 표면 중 하나로 재현할 수 있어야 한다.
| 능력 | 제품 가치 | 공개 표면 | 상태 | 필수 조건 | 실행 표면 | 검증 | 경계 |
|---|---|---|---|---|---|---|---|
| Python runtime | 브라우저 탭에서 CPython, 패키지 로드, stdout/stderr, 파일 IO를 실행한다 | boot -> 머신 핸들(machine.run/machine.fs), checkEnvironment, 탈출구 machine.runtime(Runtime, FileSystem, MemoryCapability), PAGE_SIZE는 pyproc/history |
Stable | 지원 브라우저, Pyodide 0.28.2 계열, 선택적 SRI, 제품이 내부 raw.FS 대신 공개 API를 소비 |
basic example, browser gate | npm test, npm run test:browser, npm run test:consumer |
모든 Python 패키지 보장이 아니다. 네이티브 C-extension은 Pyodide 빌드나 정적 빌드가 필요하다 |
| Deployment asset integrity | Worker, SharedWorker, Service Worker 실행 자산을 same-origin에 복사하고 바이트를 검증한다 | pyproc/assets의 getPyProcAssetManifest, verifyPyProcAssetIntegrity, registerPyProcServiceWorker, PYPROC_ASSET_MANIFEST_VERSION |
Stable | 제품 배포가 manifest의 상대 경로 구조를 보존, pyproc-assets SRI manifest 제공, Service Worker scope와 header 설정 |
asset manifest CLI, product consumer gate | npm test, npm run test:package, npm run test:consumer |
CDN URL만으로 worker graph를 여는 것은 브라우저 same-origin 정책에 막힌다 |
| Restore reactivity | 실행 경계에서 상태를 저장하고 live diff restore, time-travel, branch를 제공한다 | machine.history(checkpoint/restore/tree/prune), 내부 계약은 ReactiveController(machine.runtime.enableReactive()) |
Beta | 선언된 checkpoint 경계, 호환 runtime, 복원 가능한 heap delta | browser gate, soundness probe, exception restore probe | npm run test:browser, reactive probe |
임의 순간의 in-flight Promise, 네트워크 요청, 외부 핸들은 자동 캡처하지 않는다 |
| Process OS | Python worker를 프로세스처럼 spawn하고 snapshot-fork, live fork 팬아웃(forkMany), map, mapArray, sharded matmul, signal, IPC를 제공한다 |
machine.proc() -> PyProc, SIGNAL |
Beta | crossOriginIsolated, SharedArrayBuffer, JSPI, same-origin worker asset, 제품이 checkEnvironment() 결과를 처리 |
process OS example, speed lab, S1 artifact, S2 artifact | S1, S2 benchmark artifacts, npm run test:browser, npm run test:consumer |
POSIX fork 전체와 네이티브 shared-memory thread가 아니다. 브라우저 worker 기반 OS 모델이다. fork/forkMany의 경계 동일성은 worker 대 worker에서만 성립한다: main 커널과 worker 커널의 리플레이는 힙 길이가 같아도 바이트가 다르고(로더/컨텍스트 차이), 같은 이유로 브라우저·기기를 넘으면 힙 주소가 달라진다(내용은 같고 배치가 다름, 2026-07-17 실측 178~184p/480p). 그래서 fork는 worker끼리만 하고 PyProc은 조율자다 |
| Browser server URL | Python ASGI app을 커널 안에서 돌리고 실제 browser URL로 fetch한다 | machine.runtime.enableAsgiServer()(AsgiServer), VirtualOrigin(SW 등록은 pyproc/assets의 registerPyProcServiceWorker) |
Beta | pyprocSw.js Service Worker 등록, same-origin scope, 제품 prefix 설계 |
server dev example, product consumer gate, S3 artifact | S3 benchmark artifact, npm run test:consumer |
실제 TCP listen이 아니다. 쿠키, streaming, WebSocket은 Service Worker와 virtual origin 경계에 맞춰 따로 검증해야 한다 |
| Terminal and borrowed syscalls | 서버리스 Python terminal, blocking input, subprocess worker, sync bridge를 붙인다 | machine.term()(Terminal), machine.runtime.enableSyscallBridge()(SyscallBridge) |
Beta | JSPI 가능 브라우저, terminal UI 이벤트 배선, child worker asset | terminal example, terminal probe, syscall probe | npm run test:browser, terminal/syscall probes |
빌린 system call 계층이다. 완전한 POSIX syscall table이 아니다 |
| Environment lane | 선언된 환경(패키지/락/휠 캐시)으로 반복 실행 환경을 재현한다 | boot 매니페스트(packages/env/setup/wheelDir, 구 bootEnv/runScript 흡수), machine.runtime.enableWheelCache()(WheelCache) |
Beta | Pyodide에서 설치 가능한 wheel, lock/manifest 정합, OPFS cache | env manager campaign, PEP 723 probe, wheel cache probe | env manager probes, package consumer gate | native wheel은 그대로 가져오지 못한다. engine, lock, cache가 어긋나면 재현성이 깨진다 |
| Portable machine image | .pymachine으로 heap delta와 /home/web을 내보내고, signature와 trusted public key로 다시 연다 |
boot({ deterministic: true })(구 bootSession) + machine.history.export/save(구 Session), open(구 openMachine), 서명 체인은 pyproc/history(구 createMachineKeyPair/exportMachinePublicKey/fingerprintMachinePublicKey), Init(machine.runtime.enableInit()) |
Experimental | 같은 engine/manifest, /home/web 사용, 제품 trust key 또는 명시적 trust, resume.py hook 설계 |
machine example, product consumer gate, S4 artifact | S4 benchmark artifact, npm run test:consumer |
signature는 출처 신뢰다. 권한 허용이 아니며 fd, socket, DB connection은 resume.py가 다시 열어야 한다 |
| Machine journal | idle commit과 WAL로 crashed tab을 마지막 commit의 heap과 /home/web에서 되살린다 |
machine.history.commit/recover/watch/pack(MachineJournal) |
Experimental | OPFS, idle commit 정책, pack/prune 운영, 같은 engine/manifest | journal probe, large heap journal probe, product consumer gate | journal probes, npm run test:consumer |
장기 blob store는 pack/prune 없이 커질 수 있다. 브라우저 저장소 quota의 영향을 받는다. commit 이후 변경은 잃는다 |
| Permission jail | Python code의 net, clipboard, home, worker 권한을 제품 manifest와 CSP로 제한한다 | MachineJail(install(machine.runtime)) |
Experimental | 제품 permission manifest, jail context CSP, host allowlist, 권한 UI | jail probe, product consumer gate, trust and permissions | npm run test:consumer, jail probes |
같은 parent window에 있는 code의 모든 side channel을 제거하는 sandbox가 아니다. 강한 격리는 opaque origin 설계가 필요하다 |
| Outbound sockets | Python socket, urllib, http.client이 외부 host:port로 나가게 한다 |
SocketBridge (pyproc/socket) |
Experimental | WS-to-TCP relay, JSPI blocking recv, 제품 relay 운영 | socket campaign, Python socket probe | socket bridge probes | inbound socket은 브라우저 보안 벽이다. HTTPS는 relay가 TLS를 처리한다 |
| Device filesystem | 브라우저 기능을 Python file path로 노출한다 | machine.runtime.enableDeviceFs()(DeviceFs) |
Experimental | 제품이 허용한 device injection, 브라우저 permission, 명확한 파일 경로 정책 | product consumer gate, device FS probe, machine campaign | npm run test:consumer, device FS probes |
브라우저와 제품 정책이 허용한 장치만 존재한다 |
| GPU compute | WebGPU에 f32 array를 올려 GPU-resident linear algebra pipeline을 수행한다 | GpuCompute, GpuArray, GpuBridge (pyproc/gpu) |
Experimental | WebGPU, windowed browser, 실제 GPU, f32 데이터 경로 | GPU campaign, GPU tiled probe, GPU Python probe | GPU probes on real hardware | WGSL은 f64가 없다. headless CI 숫자는 제품 성능 근거가 아니다 |
| Immortal Python Machine | 여러 탭이 한 Python state를 공유하고 leader tab 강제 종료와 모든 탭 종료 뒤에도 마지막 commit에서 실행을 계속한다 | open({ persistent })(구 openPersistentMachine) -> KernelElection 핸들, 저널은 machine.history 내구 동사(MachineJournal) |
Experimental | Web Locks, BroadcastChannel, OPFS, 같은 origin. SAB 기반 OS 능력까지 쓰면 crossOriginIsolated와 JSPI |
immortal demo, kernel election probe, product consumer gate, S5 artifact | probe GREEN 12/12, npm run test:consumer의 immortal python machine 행, S5 failover p95 3025ms |
multi-user server가 아니다. 복구는 완료 commit 경계다. 전송 뒤 끊긴 RPC는 outcome unknown이고 자동 replay하지 않는다 |
| Machine container and jobs | 브라우저 worker 안에 별도 machine kernel을 띄우고 job control을 제공한다 | MachineContainer, JobControl(process OS 레인: machine.proc와 같은 replay 풀 전제) |
Experimental | crossOriginIsolated, worker graph, 제품의 process lifecycle 정책 |
product consumer gate, machine container probe, job control probe, pipe and shm probe | npm run test:consumer의 MachineContainer/JobControl 행, process OS probes |
Linux container나 OS scheduler가 아니다. pyproc의 browser-kernel 격리 모델이다 |
| Non-Pyodide engine seam | non-Pyodide CPython 3.14 WASI에서도 session/time-travel primitive가 동작함을 검증한다 | bootWasi, WasiSession (pyproc/wasi) |
Research preview | 소비자 제공 wasmURL, WASI worker asset, JSON value bridge |
WASI browser gate, engine port campaign, WASI REPL probe | WASI gate | production 기본 엔진이 아니다. value bridge는 JSON 중심이고 C extension은 정적 빌드가 필요하다 |
- README의 Public surface는 API 목록이다. 이 문서는 그 API를 제품 결정 단위와 실행 가능한 증거로 묶는 표다.
- 어떤 행이 Beta 이상이라도
checkEnvironment()와 제품 배포 preflight를 통과하지 않으면 기능을 켜지 않는다. - Experimental 행은 기본 기능이 아니라 명시적 제품 모드로 둔다.
- 브라우저가 물리적으로 막는 영역, 특히 inbound socket과 arbitrary native binary는 pyproc만으로 약속하지 않는다. relay, agent, static build, 또는 platform 변화가 필요하다.