fxbex 0.2.1__py3-none-any.whl

fxbex/__init__.py

@@ -0,0 +1,5 @@
+"""Independent FXBEX package builder and installed-adapter runtime."""
+__version__ = "0.2.1"
+
+from .llm import LLM
+__all__ = ['LLM']

fxbex/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

fxbex/cli.py

@@ -0,0 +1,124 @@
+"""CLI for local FXB_EX packages; SDK is imported only for runtime operations."""
+import argparse
+import json
+from pathlib import Path
+import sys
+from .package import build, inspect
+from .validation import validate
+
+
+def _main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog='fxbex', description='Build, inspect and run compiled FXB_EX model packages.',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""Examples:
+  fxbex build ./compiled_model -o model.fxbex
+  fxbex inspect model.fxbex
+  fxbex validate model.fxbex --integrity-only
+  fxbex validate model.fxbex --weights-dir ./weights
+  fxbex run model.fxbex --input inputs.json -o result.json
+  fxbex chat model.fxbex
+  fxbex serve model.fxbex --port 8000
+  fxbex doctor
+
+Validation checks static readiness; it does not run inference or prove NPU execution.
+Model-specific exporters and capture commands belong to their adapter plugins.""")
+    sub = parser.add_subparsers(dest='action', required=True)
+    p = sub.add_parser('build', help='Pack a compiled directory with checksums (no compilation)')
+    p.add_argument('source', help='Compiled directory containing manifest and required JSON configurations')
+    p.add_argument('-o', '--output', required=True, help='New .fxbex file; existing files are never overwritten')
+    p.add_argument('--standalone', action='store_true', help='Copy referenced external weights into the archive')
+    p = sub.add_parser('inspect', help='Verify integrity and display the manifest; no SDK needed')
+    p.add_argument('package', help='Path to a .fxbex archive')
+    p = sub.add_parser('validate', help='Check integrity, SDK, adapter, weights and device availability without inference')
+    p.add_argument('package', help='Path to a .fxbex archive')
+    p.add_argument('--integrity-only', action='store_true', help='Verify archive only; skip SDK, weights and device checks')
+    p.add_argument('--weights-dir', help='Override the external checkpoint/weights directory')
+    sub.add_parser('doctor', help='Report installed SDK versions and RNGD device status')
+    p = sub.add_parser('ui', help='Launch the local package interface')
+    p.add_argument('--port', type=int, default=7861, help='HTTP port (default: 7861)')
+    for name, help_text in (
+        ('run', 'Run JSON inputs or start interactive chat for a chat adapter'),
+        ('chat', 'Chat interactively, or process a messages JSON file'),
+        ('predict', 'Run a tensor DAG with named JSON inputs'),
+        ('serve', 'Serve the loaded package over local HTTP'),
+    ):
+        p = sub.add_parser(name, help=help_text, description=help_text)
+        p.add_argument('package', help='Path to a .fxbex archive')
+        p.add_argument('--report-dir', help='Directory for runtime logs and evidence')
+        p.add_argument('--weights-dir', help='Override external checkpoint/weights directory')
+        if name != 'serve':
+            p.add_argument('--input', help='JSON file: named tensors for predict, or {"messages": [...]} for chat')
+            p.add_argument('-o', '--output', help='Write response JSON to this file')
+            p.add_argument('--max-new-tokens', type=int, default=32, help='Chat token limit (default: 32)')
+        else:
+            p.add_argument('--port', type=int, default=8000, help='HTTP port (default: 8000)')
+    args=parser.parse_args(argv)
+    if args.action=='build':result={'package':str(build(args.source,args.output,standalone=args.standalone))}
+    elif args.action == 'inspect':
+        m=inspect(args.package)
+        result={'model':m['model'],'runtime':m['runtime'],'compatibility':m['compatibility'],
+                'standalone':m['standalone'],'files':len(m['files']),
+                'artifact_bytes':sum(x['size'] for x in m['files'].values()),'integrity_verified':True}
+    elif args.action == 'validate':
+        result = validate(args.package, integrity_only=args.integrity_only, weights_dir=args.weights_dir)
+    elif args.action=='doctor':
+        from .runtime import doctor
+        result=doctor()
+    elif args.action=='ui':
+        from .ui import launch
+        launch(args.port);return
+    else:
+        from .runtime import Session
+        # SDK/compiler diagnostics may print; keep JSON results on stdout.
+        import contextlib
+        if args.action == 'predict' and not args.input:
+            raise ValueError('--input JSON file is required for tensor prediction')
+        session=Session(args.package,report_dir=args.report_dir,weights_dir=args.weights_dir)
+        log_path=session.report_dir/'runtime.log'
+        print(f'Loading package; diagnostics: {log_path}',file=sys.stderr,flush=True)
+        with log_path.open('w') as log, contextlib.redirect_stdout(log), contextlib.redirect_stderr(log):
+            session.__enter__()
+        print(f'NPU package ready; reports: {session.report_dir}',file=sys.stderr,flush=True)
+        try:
+            if args.action=='serve':
+                from .server import serve
+                serve(session,args.port);return
+            if args.action=='predict' or (args.action=='run' and session.manifest['runtime']['adapter']=='runnable_dag'):
+                if not args.input:raise ValueError('--input JSON file is required for tensor prediction')
+                result=session.predict(json.loads(Path(args.input).read_text()))
+            elif args.input:
+                data=json.loads(Path(args.input).read_text())
+                result=session.chat(data['messages'],data.get('max_new_tokens',args.max_new_tokens))
+            else:
+                messages=[]
+                print('FXB_EX chat: /reset clears history, /quit unloads.',flush=True)
+                while True:
+                    try:prompt=input('you> ')
+                    except EOFError:break
+                    if prompt.strip()=='/quit':break
+                    if prompt.strip()=='/reset':messages=[];continue
+                    if not prompt.strip():continue
+                    candidate=messages+[{'role':'user','content':prompt}]
+                    result=session.chat(candidate,args.max_new_tokens)
+                    messages=candidate+[{'role':'assistant','content':result['text']}]
+                    print(result['text'],flush=True)
+                return
+        finally:session.__exit__(None,None,None)
+        if args.output:Path(args.output).write_text(json.dumps(result,ensure_ascii=False,indent=2))
+        result['report_dir']=str(session.report_dir)
+    print(json.dumps(result,ensure_ascii=False,indent=2))
+    return 0 if result.get('valid', True) else 1
+
+def main(argv=None):
+    try:
+        return _main(argv) or 0
+    except Exception as exc:
+        print(f'fxbex: {exc}', file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == '__main__':
+    sys.exit(main())

fxbex/llm.py

@@ -0,0 +1,52 @@
+"""Small process-isolated Python interface for validated chat packages."""
+import threading
+from .package import inspect
+from .service import PackageService
+
+
+class LLM:
+    """Load an FXBEX chat package once. Close explicitly or use a with block.
+
+    fxb is an alias for fxbex; neither converts an official Furiosa FXB.
+    Model identity must match the package. No implicit downloads or compilation.
+    """
+    def __init__(self, model=None, *, fxbex=None, fxb=None):
+        if (fxbex is None)==(fxb is None):
+            raise ValueError('Specify exactly one of fxbex= or fxb= with an FXBEX package')
+        path=fxbex if fxbex is not None else fxb
+        # Validate content rather than trusting the filename extension.
+        try:manifest=inspect(path)
+        except (ValueError, OSError) as exc:
+            raise ValueError('Expected an FXBEX package; official .fxb requires furiosa_llm.LLM') from exc
+        if model is not None and model!=manifest['model']['name']:
+            raise ValueError(f"Model mismatch: requested {model!r}, package contains {manifest['model']['name']!r}")
+        self.model=manifest['model']['name'];self.history=[]
+        self._lock=threading.RLock();self._service=PackageService(path)
+        self._service.load()
+
+    def chat(self, messages, max_new_tokens=32):
+        """Return a result dict (text, metrics); caller supplies explicit history."""
+        with self._lock:return self._service.chat(messages,max_new_tokens)
+
+    def generate(self, prompt, max_new_tokens=32):
+        """Single-turn generation, returning the same result dict as chat."""
+        return self.chat([{'role':'user','content':prompt}],max_new_tokens)
+
+    def converse(self, prompt, max_new_tokens=32):
+        """Keep successful turns until reset(); failed calls do not mutate history."""
+        with self._lock:
+            messages=self.history+[{'role':'user','content':prompt}]
+            result=self.chat(messages,max_new_tokens)
+            self.history=messages+[{'role':'assistant','content':result['text']}]
+            return result
+
+    def reset(self):
+        with self._lock:self.history=[]
+
+    def close(self):
+        with self._lock:self._service.unload()
+
+    unload=close
+
+    def __enter__(self):return self
+    def __exit__(self,*args):self.close()

fxbex/package.py

@@ -0,0 +1,258 @@
+"""Model-independent FXB_EX archives; this is not Furiosa's official FXB format."""
+from contextlib import contextmanager
+import hashlib
+import io
+import json
+import os
+from pathlib import Path, PurePosixPath
+import stat
+import tempfile
+import zipfile
+
+REQUIRED = ('execution_plan.json', 'weights_index.json', 'memory_plan.json', 'runtime_config.json')
+DEFAULT_MAX_TOTAL_SIZE = 64 * 1024**3
+DEFAULT_MAX_JSON_SIZE = 16 * 1024**2
+CHUNK = 1024**2
+
+
+class PackageError(ValueError):
+    """An invalid or unsafe FXB_EX package."""
+
+
+def _name(name):
+    if (not isinstance(name, str) or not name or '\\' in name or '\x00' in name
+            or ':' in name or name.startswith('/')
+            or any(p in ('', '.', '..') for p in name.split('/'))):
+        raise PackageError(f'Unsafe member path: {name!r}')
+    return name
+
+
+def _json(data, label):
+    def pairs(items):
+        result = {}
+        for key, value in items:
+            if key in result:
+                raise PackageError(f'Duplicate JSON key in {label}: {key}')
+            result[key] = value
+        return result
+    try:
+        value = json.loads(data, object_pairs_hook=pairs)
+    except (ValueError, UnicodeError) as exc:
+        raise PackageError(f'Invalid JSON in {label}: {exc}') from exc
+    if not isinstance(value, dict):
+        raise PackageError(f'{label} must be a JSON object')
+    return value
+
+
+def _manifest(manifest):
+    if type(manifest.get('schema_version')) is not int or manifest['schema_version'] != 1 or manifest.get('format') != 'FXB_EX':
+        raise PackageError('Expected FXB_EX schema_version 1')
+    if (not isinstance(manifest.get('model'), dict)
+            or not isinstance(manifest['model'].get('name'), str) or not manifest['model']['name']):
+        raise PackageError('manifest.model.name is required')
+    if not isinstance(manifest.get('compatibility'), dict):
+        raise PackageError('manifest.compatibility must be an object')
+    runtime = manifest.get('runtime')
+    if not isinstance(runtime, dict) or not isinstance(runtime.get('adapter'), str) or not runtime['adapter']:
+        raise PackageError('manifest.runtime.adapter is required')
+    if not isinstance(manifest.get('standalone'), bool):
+        raise PackageError('manifest.standalone must be boolean')
+    files = manifest.get('files')
+    if not isinstance(files, dict) or not set(REQUIRED).issubset(files):
+        raise PackageError('Integrity map must include every required configuration')
+    for name, item in files.items():
+        _name(name)
+        if name == 'manifest.json' or not isinstance(item, dict):
+            raise PackageError(f'Invalid integrity entry: {name}')
+        digest = item.get('sha256')
+        if (not isinstance(digest, str) or len(digest) != 64
+                or any(c not in '0123456789abcdef' for c in digest)
+                or type(item.get('size')) is not int or item['size'] < 0):
+            raise PackageError(f'Invalid checksum or size: {name}')
+
+
+def _weights(index, manifest):
+    weights = index.get('weights')
+    if not isinstance(weights, list):
+        raise PackageError('weights_index.weights must be a list')
+    for weight in weights:
+        if not isinstance(weight, dict) or ('path' in weight) == ('external_path' in weight):
+            raise PackageError('Each weight needs exactly one path or external_path')
+        if 'path' in weight:
+            if _name(weight['path']) not in manifest['files']:
+                raise PackageError(f'Missing packaged weight: {weight["path"]}')
+        elif manifest['standalone']:
+            raise PackageError('Standalone packages cannot reference external weights')
+        elif not isinstance(weight['external_path'], str) or not weight['external_path']:
+            raise PackageError('external_path must be a nonempty string')
+
+
+def _validate(archive, max_total_size, max_json_size):
+    if max_total_size <= 0 or max_json_size <= 0:
+        raise ValueError('Size limits must be positive')
+    members = {}
+    total = 0
+    for info in archive.infolist():
+        name = _name(info.filename)
+        mode = info.external_attr >> 16
+        if name in members or info.is_dir() or stat.S_ISLNK(mode) or (stat.S_IFMT(mode) not in (0, stat.S_IFREG)):
+            raise PackageError(f'Duplicate or unsupported member: {name}')
+        if info.flag_bits & 1:
+            raise PackageError('Encrypted members are unsupported')
+        total += info.file_size
+        if total > max_total_size:
+            raise PackageError('Package exceeds total uncompressed size limit')
+        members[name] = info
+    for name in members:
+        if any(str(parent) in members for parent in PurePosixPath(name).parents if str(parent) != '.'):
+            raise PackageError(f'Member conflicts with parent file: {name}')
+    for name in ('manifest.json', *REQUIRED):
+        if name not in members:
+            raise PackageError(f'Missing required member: {name}')
+        if members[name].file_size > max_json_size:
+            raise PackageError(f'JSON exceeds size limit: {name}')
+    manifest = _json(archive.read('manifest.json'), 'manifest.json')
+    _manifest(manifest)
+    if set(members) != {'manifest.json', *manifest['files']}:
+        raise PackageError('Archive members do not match manifest integrity map')
+    for name, entry in manifest['files'].items():
+        if members[name].file_size != entry['size']:
+            raise PackageError(f'Size mismatch: {name}')
+        digest = hashlib.sha256()
+        with archive.open(name) as stream:
+            while chunk := stream.read(CHUNK):
+                digest.update(chunk)
+        if digest.hexdigest() != entry['sha256']:
+            raise PackageError(f'Checksum mismatch: {name}')
+    configs = {name: _json(archive.read(name), name) for name in REQUIRED}
+    _weights(configs['weights_index.json'], manifest)
+    return manifest
+
+
+def validate(path, *, max_total_size=DEFAULT_MAX_TOTAL_SIZE, max_json_size=DEFAULT_MAX_JSON_SIZE):
+    """Verify member safety, bounded sizes, required JSONs and all SHA-256 checksums.
+
+    External weight existence and runtime/NPU compatibility are not checked.
+    """
+    try:
+        with zipfile.ZipFile(path) as archive:
+            return _validate(archive, max_total_size, max_json_size)
+    except (zipfile.BadZipFile, RuntimeError, NotImplementedError) as exc:
+        raise PackageError(f'Unreadable archive: {exc}') from exc
+
+
+def inspect(path, **limits):
+    """Return the manifest only after full archive validation."""
+    return validate(path, **limits)
+
+
+@contextmanager
+def extract(path, *, max_total_size=DEFAULT_MAX_TOTAL_SIZE, max_json_size=DEFAULT_MAX_JSON_SIZE):
+    """Yield a validated temporary package directory, deleting it on exit.
+
+    One open archive is used for validation and extraction to avoid path replacement.
+    """
+    try:
+        with zipfile.ZipFile(path) as archive:
+            _validate(archive, max_total_size, max_json_size)
+            with tempfile.TemporaryDirectory(prefix='fxbex-') as directory:
+                root = Path(directory)
+                for info in archive.infolist():
+                    target = root.joinpath(*PurePosixPath(info.filename).parts)
+                    target.parent.mkdir(parents=True, exist_ok=True)
+                    with archive.open(info) as source, target.open('xb') as dest:
+                        while chunk := source.read(CHUNK):
+                            dest.write(chunk)
+                yield root
+    except (zipfile.BadZipFile, RuntimeError, NotImplementedError) as exc:
+        raise PackageError(f'Unreadable archive: {exc}') from exc
+
+
+def build(source, output, standalone=False, *, max_total_size=DEFAULT_MAX_TOTAL_SIZE, max_json_size=DEFAULT_MAX_JSON_SIZE):
+    """Build atomically without overwriting; source is an unpacked package tree.
+
+    Source manifest supplies model, compatibility and runtime. Integrity entries and
+    standalone are generated. weights_index uses {"weights": [{"path": "weights/a"}]}
+    for internal weights or {"external_path": "/deployment/a"} for external weights.
+    In standalone mode external files are streamed into weights/ and their index
+    entries are rewritten in the archive only. Relative external paths resolve
+    against source; explicit external symlinks are resolved (e.g. HF cache blobs).
+    """
+    source = Path(source).resolve()
+    output = Path(output).absolute()
+    if not source.is_dir():
+        raise PackageError('Source must be a directory')
+    if output.resolve().is_relative_to(source):
+        raise PackageError('Output must be outside the source directory')
+    if output.exists() or output.is_symlink():
+        raise FileExistsError(output)
+    manifest_path = source / 'manifest.json'
+    if manifest_path.is_symlink() or not manifest_path.is_file():
+        raise PackageError('Source requires a regular manifest.json')
+    if manifest_path.stat().st_size > max_json_size:
+        raise PackageError('Manifest exceeds JSON size limit')
+    manifest = _json(manifest_path.read_bytes(), 'manifest.json')
+    manifest.update(schema_version=1, format='FXB_EX', standalone=bool(standalone), files={})
+    inputs = {}
+    for path in sorted(source.rglob('*')):
+        if path.is_symlink():
+            raise PackageError(f'Source symlinks are forbidden: {path}')
+        if path.is_dir():
+            continue
+        if not path.is_file():
+            raise PackageError(f'Source must contain regular files: {path}')
+        name = _name(path.relative_to(source).as_posix())
+        if name != 'manifest.json':
+            inputs[name] = (path, None)
+    if standalone:
+        index_path = source / 'weights_index.json'
+        if not index_path.is_file() or index_path.stat().st_size > max_json_size:
+            raise PackageError('Missing or oversized weights_index.json')
+        index = _json(index_path.read_bytes(), 'weights_index.json')
+        # Validate the original references before replacing external entries.
+        _weights(index, {'standalone': False, 'files': inputs})
+        for weight in index['weights']:
+            if 'external_path' not in weight:
+                continue
+            external = Path(weight['external_path'])
+            basename = weight.get('name', external.name)
+            _name(basename)
+            if '/' in basename:
+                raise PackageError(f'Weight name must be a basename: {basename}')
+            name = 'weights/' + basename
+            if name in inputs:
+                raise PackageError(f'Weight path collision: {name}')
+            external = (external if external.is_absolute() else source / external).resolve()
+            if not external.is_file():
+                raise PackageError(f'Missing external weight file: {external}')
+            inputs[name] = (external, weight.get('sha256'))
+            del weight['external_path']
+            weight['path'] = name
+        inputs['weights_index.json'] = (json.dumps(index, sort_keys=True).encode(), None)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix='.fxbex-', dir=output.parent)
+    os.close(fd)
+    try:
+        total = 0
+        with zipfile.ZipFile(temporary, 'w', compression=zipfile.ZIP_STORED, allowZip64=True) as archive:
+            for name, (item, expected_digest) in inputs.items():
+                digest = hashlib.sha256()
+                size = 0
+                with (io.BytesIO(item) if isinstance(item, bytes) else item.open('rb')) as stream:
+                    with archive.open(name, 'w', force_zip64=True) as dest:
+                        while chunk := stream.read(CHUNK):
+                            size += len(chunk)
+                            total += len(chunk)
+                            if total > max_total_size:
+                                raise PackageError('Source exceeds total size limit')
+                            dest.write(chunk)
+                            digest.update(chunk)
+                if expected_digest is not None and digest.hexdigest() != expected_digest:
+                    raise PackageError(f'External weight checksum mismatch: {name}')
+                manifest['files'][name] = {'sha256': digest.hexdigest(), 'size': size}
+            archive.writestr('manifest.json', json.dumps(manifest, sort_keys=True, indent=2) + '\n')
+        validate(temporary, max_total_size=max_total_size, max_json_size=max_json_size)
+        os.link(temporary, output)  # Atomic publication with no overwrite.
+        return output
+    finally:
+        os.unlink(temporary)

fxbex/replay.py

@@ -0,0 +1,209 @@
+"""Exact-request replay of SDK Runnable bytes, not standalone native EDF execution."""
+from contextlib import contextmanager
+from dataclasses import dataclass, fields, is_dataclass
+from enum import Enum
+import hashlib
+import importlib
+import importlib.metadata
+import json
+from pathlib import Path
+import platform
+import re
+
+
+class ReplayError(RuntimeError):
+    pass
+
+
+@dataclass
+class ReplayStats:
+    compile_calls: int = 0
+    replay_hits: int = 0
+
+
+def _json(value):
+    return json.dumps(value, sort_keys=True, separators=(',', ':'), allow_nan=False)
+
+
+def _hash(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+def _compatibility(torch, sdk):
+    versions = {}
+    for name in ('furiosa-torch', 'furiosa-tcc'):
+        try:
+            versions[name] = importlib.metadata.version(name)
+        except importlib.metadata.PackageNotFoundError:
+            versions[name] = None
+    sources = {}
+    if getattr(sdk, '__file__', None):
+        directory = Path(sdk.__file__).parent
+        for relative in ('compiler/__init__.py', '_module/runnable.py', '_backend/torch_compile.py'):
+            path = directory / relative
+            sources[relative] = _hash(path.read_bytes()) if path.is_file() else None
+    return {'python': platform.python_version(), 'platform': platform.platform(),
+            'torch': torch.__version__, 'sdk': versions, 'sdk_sources': sources}
+
+
+def _value(value, torch, *, tensor_data=False):
+    if value is None or type(value) in (str, int, bool):
+        return value
+    if type(value) is float:
+        return {'float': value.hex()}
+    if isinstance(value, torch.fx.Node):
+        return {'node': value.name}
+    if isinstance(value, torch.Tensor):
+        result = {'tensor': {'shape': [_value(x, torch) for x in value.shape],
+                            'stride': [_value(x, torch) for x in value.stride()],
+                            'dtype': str(value.dtype), 'device': str(value.device),
+                            'layout': str(value.layout), 'requires_grad': value.requires_grad,
+                            'storage_offset': _value(value.storage_offset(), torch),
+                            'conjugate': value.is_conj(), 'negative': value.is_neg()}}
+        if tensor_data:
+            if value.numel() * value.element_size() > 1024 * 1024:
+                raise ReplayError('Constant tensor exceeds 1 MiB; lift it into an input')
+            if value.device.type != 'cpu' or value.layout != torch.strided:
+                raise ReplayError('Only dense CPU tensor constants are supported')
+            try:
+                raw = value.detach().contiguous().reshape(-1).view(torch.uint8).numpy().tobytes()
+            except Exception as exc:
+                raise ReplayError('Cannot read tensor constant') from exc
+            result['sha256'] = _hash(raw)
+        return result
+    if isinstance(value, (torch.dtype, torch.device, torch.layout, torch.memory_format)):
+        return {'torch_type': str(value)}
+    if isinstance(value, Enum):
+        return {'enum': type(value).__module__ + '.' + type(value).__qualname__, 'name': value.name}
+    if is_dataclass(value) and not isinstance(value, type):
+        return {'dataclass': type(value).__module__ + '.' + type(value).__qualname__,
+                'fields': {f.name: _value(getattr(value, f.name), torch, tensor_data=tensor_data)
+                           for f in fields(value)}}
+    if type(value) in (list, tuple, torch.fx.immutable_collections.immutable_list):
+        return {type(value).__name__: [_value(x, torch, tensor_data=tensor_data) for x in value]}
+    if type(value) in (dict, torch.fx.immutable_collections.immutable_dict) and all(type(k) is str for k in value):
+        return {k: _value(v, torch, tensor_data=tensor_data) for k, v in value.items()}
+    if isinstance(value, slice):
+        return {'slice': [_value(v, torch) for v in (value.start, value.stop, value.step)]}
+    raise ReplayError(f'Unsupported key value: {type(value).__module__}.{type(value).__qualname__}')
+
+
+def _request(ep, config, task_name, torch):
+    if config is not None:
+        if not type(config).__module__.startswith('furiosa.'):
+            raise ReplayError('Unsupported compiler configuration type')
+        config_text = str(config)
+        if re.search(r' at 0x[0-9a-fA-F]+', config_text):
+            raise ReplayError('Compiler configuration has no stable string form')
+        config = {'type': type(config).__module__ + '.' + type(config).__qualname__, 'value': config_text}
+    nodes = []
+    for node in ep.graph.nodes:
+        target = node.target
+        if not isinstance(target, str):
+            if isinstance(target, (torch._ops.OpOverload, torch._ops.OpOverloadPacket)):
+                target = str(target)
+            elif getattr(target, '__module__', None) in ('operator', '_operator', 'builtins'):
+                target = target.__module__ + '.' + target.__qualname__
+            else:
+                raise ReplayError(f'Unsupported graph target: {target!r}')
+        if node.op in ('get_attr', 'call_module'):
+            raise ReplayError('Graph attributes/modules must be lifted into explicit inputs')
+        nodes.append({'name': node.name, 'op': node.op, 'target': target,
+                      'args': _value(node.args, torch, tensor_data=True),
+                      'kwargs': _value(node.kwargs, torch, tensor_data=True),
+                      'value': _value(node.meta.get('val'), torch)})
+    return {'nodes': nodes, 'signature': _value(ep.graph_signature, torch),
+            'constants': _value(ep.constants, torch, tensor_data=True),
+            'config': config}
+
+
+@contextmanager
+def _session(root, recording, guard_native=True):
+    torch = importlib.import_module('torch')
+    compiler = importlib.import_module('furiosa.torch.compiler')
+    sdk = importlib.import_module('furiosa.torch')
+    ir = sdk.ir
+    root = Path(root)
+    plan_path = root / 'execution_plan.json'
+    compatibility = _compatibility(torch, sdk)
+    if recording:
+        if plan_path.exists():
+            raise ReplayError('Refusing to overwrite an existing execution plan')
+        (root / 'edfs').mkdir(parents=True, exist_ok=True)
+        plan = {'format': 'sdk-runnable', 'version': 1, 'compatibility': compatibility, 'steps': []}
+    else:
+        plan = json.loads(plan_path.read_text())
+        if (plan.get('format') != 'sdk-runnable' or plan.get('version') != 1
+                or plan.get('compatibility') != compatibility):
+            raise ReplayError('Runnable plan format or environment compatibility mismatch')
+    records = {}
+    for record in plan['steps']:
+        key = record['key']
+        if key in records or _hash(_json(record['args']).encode()) != key:
+            raise ReplayError('Duplicate or invalid request key')
+        if record['path'] != f'edfs/{key}.runnable':
+            raise ReplayError('Invalid runnable path')
+        records[key] = record
+    original = compiler.compile
+    stats = ReplayStats()
+
+    def compile(ep, compiler_config=None, *, task_name=None):
+        effective_config = compiler_config if compiler_config is not None else sdk.config.get_compiler_config()
+        args = _request(ep, effective_config, task_name, torch)
+        key = _hash(_json(args).encode())
+        if recording:
+            stats.compile_calls += 1
+            runnable = original(ep, compiler_config, task_name=task_name)
+            data = bytes(runnable.serialize())
+            record = {'key': key, 'path': f'edfs/{key}.runnable', 'sha256': _hash(data), 'args': args}
+            if key in records and records[key] != record:
+                raise ReplayError('Identical request produced different runnable bytes')
+            if key not in records:
+                path = root / record['path']
+                if path.exists() and path.read_bytes() != data:
+                    raise ReplayError('Conflicting existing runnable file')
+                path.write_bytes(data)
+                records[key] = record
+                plan['steps'].append(record)
+            return runnable
+        if key not in records:
+            raise ReplayError(f'No recorded runnable for request {key}; compilation is forbidden')
+        record = records[key]
+        path = root / record['path']
+        if path.resolve().parent != (root / 'edfs').resolve() or path.is_symlink():
+            raise ReplayError('Runnable path escapes package')
+        data = path.read_bytes()
+        if _hash(data) != record['sha256']:
+            raise ReplayError('Runnable checksum mismatch')
+        runnable = ir.Runnable.deserialize(data)
+        stats.replay_hits += 1
+        return runnable
+
+    def forbidden(*args, **kwargs):
+        raise ReplayError('Native compiler entry point is forbidden during replay')
+
+    patches = [(compiler, 'compile', original)]
+    try:
+        compiler.compile = compile
+        if not recording and guard_native:
+            native = importlib.import_module('furiosa.torch._C')
+            for name in ('compile', 'compile_raw_dfg'):
+                if hasattr(native.compiler, name):
+                    patches.append((native.compiler, name, getattr(native.compiler, name)))
+                    setattr(native.compiler, name, forbidden)
+        yield stats
+        if recording:
+            plan_path.write_text(_json(plan) + '\n')
+    finally:
+        for obj, name, value in reversed(patches):
+            setattr(obj, name, value)
+
+
+def capture(root):
+    """Capture public compile calls and write an execution plan on successful exit."""
+    return _session(root, True)
+
+
+def replay(root, *, guard_native=True):
+    """Restore exact captured requests; tracing/lowering still occurs, compilation cannot."""
+    return _session(root, False, guard_native)