From daa5309ea930b392e27f461a025d3aa20c892420 Mon Sep 17 00:00:00 2001 From: Selfhosting Dev Date: Sat, 20 Sep 2025 09:05:20 +0900 Subject: [PATCH] docs: fix macro sandbox policy and lock minimal Box API (Console/String/Array/Map); clarify plugin-off applies to macro child only --- docs/reference/macro/capabilities.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/reference/macro/capabilities.md b/docs/reference/macro/capabilities.md index f0c45e63..f1691250 100644 --- a/docs/reference/macro/capabilities.md +++ b/docs/reference/macro/capabilities.md @@ -14,6 +14,26 @@ Status: Design/PoC. This document defines the capability model for user macros e Default: all OFF (io=false, net=false, env=false) +## Stable Minimal Box API (macro sandbox) +User macros executed in the sandbox must not depend on external plugins. The following core Boxes and methods are guaranteed to exist and remain stable for macro authors (MVP scope): + +- ConsoleBox + - `print/println/log(string)` +- String (receiver is Python-style string in PyVM sandbox) + - `length() -> int` + - `substring(start:int, end:int) -> string` + - `lastIndexOf(substr:string) -> int` + - `esc_json() -> string` (escape for JSON embedding) +- ArrayBox + - `size() -> int`, `get(i:int) -> any`, `set(i:int, v:any)`, `push(v:any)` +- MapBox + - `size() -> int`, `has(key:string) -> bool`, `get(key:string) -> any`, `set(key:string, v:any)`, `toString() -> string` + +Notes +- These APIs are available only inside the macro sandbox child. Application execution (PyVM/LLVM) continues to use the normal plugin system. +- The sandbox disables plugins by default (`NYASH_DISABLE_PLUGINS=1`) to ensure determinism; only the above minimal Boxes are relied upon by macros. +- Built-in core normalization (for/foreach → Loop, match → If, Loop tail alignment) does not use Boxes and is not affected by plugin state. + ## Behavior per Capability - io=false - Disable FileBox and other I/O boxes in the macro sandbox. @@ -66,4 +86,3 @@ Phase‑2 PoC maps these to the child process environment/sandbox: - Keep macros pure (operate only on AST JSON v0) unless there is a strong case for capabilities. - Treat `net=true` as exceptional and subject to policy review, due to determinism concerns. - Prefer deterministic inputs (versioned data files) if `io=true` is deemed necessary in future. -