Complete the documentation set for the M0.5 toolchain, grounded in the code: - spec/references.md: import/reference/call edges, identities, loader rules, anchors, `ref` resolution/ambiguity, `check --refs` validation. - spec/value-wire.md: exact wire_version 1 typed encoding, integer-as-decimal string rule, special floats, limits and exact float round-trip. - spec/security.md: modes (strict refuses without OS isolation), capabilities, path rules, budgets, tracing, foreign process caveats, plugin trust. - spec/package-format.md: marqdo.yaml/lock formats, validation, lock/sync, unsupported registry/git/environment work. - spec/plugin-abi.md: ABI v1 layout/ownership/negotiation, manifest/artifact rules, wire envelopes, loader lifecycle, trust boundary, SDK/C demo, and the implemented CLI plugin-invocation flow with its limitations. - spec/math.md and spec/foreign.md: the implemented math subset and the foreign request/response/timeout/capability contract. - docs/adr/0001..0007: accepted decisions for the span foundation, inert executables outside function bodies, ref ambiguity (S-07), strict refusal, AST normalization, CLI contract and BigInt/typed wire (S-08). - docs/contributor-guide.md: repo map, workflow, fixture/golden updates, quality gate, ADR/commit policy. - docs/STATUS.md: P0-P7 matrix with evidence, open items and the blueprint §18 Alpha checklist (conclusion: not yet Alpha-complete), including known divergences rather than overclaims. - README.md rewritten from "design-only starter" to the working implementation with quickstart, implemented phases, deliberate limits and doc index. - AGENTS.md: updated pointers/workflow only; architectural rules unchanged. - Consistency fixes in spec/mapping.md/evaluation.md (inert emph outside functions, unsupported math.simplify/differentiate).
6.0 KiB
ADR-0004: Strict mode refuses to run without OS isolation
Status: Accepted Date: 2026-11-20
Context
Blueprint §9 defines three execution modes and one non-negotiable rule:
strict: untrusted documents/code/plugins — independent restricted process, OS-level resource and syscall/file/network restrictions; if unavailable, refuse to run.
A cooperative in-process capability check cannot contain hostile native code
or an unrestricted child process. If strict silently degraded to project,
users would believe they had isolation they did not have. That is a security
bug, not a missing feature.
M0.5 implements capability checks, budgets and process supervision but no OS isolation adapter (no Linux namespaces/seccomp/cgroups, no Windows Job Object/appcontainer, no macOS sandbox), and the isolated plugin worker transport is not implemented either.
Decision
crates/marqdo-sandboxis honest about platform support:PlatformCapabilities::detect()always reportsStrictIsolation::Unavailable { reason }in this build, with a platform-specific reason (Linux: "no OS isolation adapter (namespaces/seccomp/cgroups) is implemented in this build"; macOS/Windows/ other targets have analogous messages);worker_processes: false.
marqdo_sandbox::enforce(mode, platform):pureandproject→Ok(());strict→Err(SandboxError::StrictUnavailable { reason })unlessplatform.strict.is_available().
run/callcallenforcebefore constructing the host, loading plugins or executing anything. On failure they print "refusing to run in strict mode: ..." (or a JSON{"success":false, "error":...}envelope) and exit 1.- There is no fallback: the CLI never downgrades a requested strict run to
project mode.
SandboxMode::parse("strict")succeeds (the mode name is valid); only execution is refused. inspect --platformexposes the detection report so users can see why:{"os":"linux","arch":"x86_64","strict":{"state":"unavailable","reason":...}, "worker_processes":false}.- The rest of the system is labelled accordingly:
projectmode is cooperative, in-process, and is not a sandbox; foreign kernels are process-isolated but not confined; native plugins run in-process and require explicit trust (ADR-0006/security spec).
Alternatives
- Best-effort strict (run with the same checks as project). Rejected: it directly violates the blueprint's "cannot provide → refuse" rule and hides a missing security boundary.
- Warn and continue. Rejected for the same reason; a warning is not a sandbox, and CI/agents may not read warnings.
- Implement a Linux namespaces/seccomp adapter now. Out of scope for M0.5: it needs platform-specific code, integration tests, resource limits, CI on multiple kernels, and a way to supervise the worker protocol. This is P4 work and belongs in its own ADR when implemented.
- Use Wasm/WASI for strict. Attractive for plugins later, but it does not
sandbox arbitrary Python/Node processes or native
.sofiles, and the runtime is not implemented. Rejected for now. - Claim strict via the process isolation of foreign kernels. Rejected: a child process inherits the user's privileges and filesystem/network access; changing cwd and clearing env is hygiene, not confinement.
Markdown AST shape
No language or AST change. A strict run is rejected before any document is executed (after static loading/diagnostics); the CLI contract is:
$ marqdo run index.mq.md --mode strict
error: refusing to run in strict mode: no OS isolation adapter
(namespaces/seccomp/cgroups) is implemented in this build. Strict mode
requires verified OS-level isolation and never falls back to an
unrestricted process.
$ echo $?
1
(Exact wording comes from
crates/marqdo-sandbox/src/lib.rs::SandboxError::display.)
Compatibility
- Accepting
--mode strictas a valid name is part of the CLI contract; the refusal is a documented behavior, not a parse error. A future release that implements isolation flips the detection report and starts executing strict runs — that is the intended upgrade path. - Exit code 1 (runtime/security refusal) is stable; usage errors are 2.
PlatformCapabilitiesJSON shape (state: available|unavailable) is versioned by documentation and should not change without an ADR.- No package/ABI/wire impact.
Security
- The guarantee "requested strict → refused rather than downgraded" is
enforced in code (
enforce), not documentation. - Users cannot accidentally believe untrusted docs are sandboxed by this build; the platform report is the evidence.
- Project mode remains explicitly non-sandboxed. Native plugins (in-process) and foreign child processes are recorded as trust decisions, not isolation.
- Secrets: strict refusal happens before plugin loading or foreign spawning, so no untrusted code is touched by a refused command.
Testing
crates/marqdo-sandbox/src/lib.rs::tests:: strict_refuses_when_isolation_is_unavailableasserts the refusal and thatpure/projectstill succeed.mode_names_round_tripcovers parsing/printing.- CLI behavior (
--mode strictexit 1, message) is covered by manual/CLI smoke checks; a CLI integration test should be added with the conformance harness. inspect --platformJSON is exercised manually and in the CLI help/example documentation; it should get a golden test in the fixture workstream.
Migration & rollout
When an OS isolation adapter lands:
- implement a
StrictIsolation::Available { mechanism }report and a real supervisor/worker; - add integration tests for filesystem/network/process restrictions and resource limits per platform, plus the platform capability matrix;
- update
spec/security.md, this ADR (or supersede it),docs/STATUS.mdand the CLI docs; - only then change
PlatformCapabilities::detect; do not add a flag that bypasses the refusal before that work is done.