Files
marqdo-cli/docs/adr/0004-strict-mode-refuses-without-isolation.md
T
cflmy 0116160399 docs: formal specs, ADRs, STATUS matrix, contributor guide and honest README
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).
2026-11-20 10:56:26 +08:00

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

  1. crates/marqdo-sandbox is honest about platform support:
    • PlatformCapabilities::detect() always reports StrictIsolation::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.
  2. marqdo_sandbox::enforce(mode, platform):
    • pure and project → Ok(());
    • strict → Err(SandboxError::StrictUnavailable { reason }) unless platform.strict.is_available().
  3. run/call call enforce before 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.
  4. 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.
  5. inspect --platform exposes the detection report so users can see why: {"os":"linux","arch":"x86_64","strict":{"state":"unavailable","reason":...}, "worker_processes":false}.
  6. The rest of the system is labelled accordingly: project mode 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

  1. 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.
  2. Warn and continue. Rejected for the same reason; a warning is not a sandbox, and CI/agents may not read warnings.
  3. 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.
  4. Use Wasm/WASI for strict. Attractive for plugins later, but it does not sandbox arbitrary Python/Node processes or native .so files, and the runtime is not implemented. Rejected for now.
  5. 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 strict as 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.
  • PlatformCapabilities JSON 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_unavailable asserts the refusal and that pure/project still succeed.
  • mode_names_round_trip covers parsing/printing.
  • CLI behavior (--mode strict exit 1, message) is covered by manual/CLI smoke checks; a CLI integration test should be added with the conformance harness.
  • inspect --platform JSON 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:

  1. implement a StrictIsolation::Available { mechanism } report and a real supervisor/worker;
  2. add integration tests for filesystem/network/process restrictions and resource limits per platform, plus the platform capability matrix;
  3. update spec/security.md, this ADR (or supersede it), docs/STATUS.md and the CLI docs;
  4. only then change PlatformCapabilities::detect; do not add a flag that bypasses the refusal before that work is done.