# ADR 0096: Managed file boundaries own safe read semantics

> Source: https://github.com/max-listov/stitchkit/blob/master/docs/decisions/0096-managed-file-boundary-owns-safe-read-semantics.md

---

# ADR 0096 — Managed file boundaries own safe read semantics

## Context

ADR 0088 unified containment and writes, but applications still created the
root separately, read inspection was asymmetric, and expected filesystem
failures could surface as generic internal errors or leak host details through
different adapters.

## Decision

`createManagedFileBoundary({ createRoot: true })` may create exactly the final
root directory, non-recursively and with private permissions, beneath an
already-existing trusted parent. The default still requires an existing root.
Canonical containment and root symlink policy are unchanged.

The same bounded inspector runs for reads and writes, receives only the
configured prefix plus a caller/deadline signal, and cannot replace
framework-owned path or measured size. `inspectionTimeoutMs` bounds a
non-cooperative inspector from the caller's perspective. Read inspection gets
an isolated prefix copy, so an untrusted inspector cannot mutate returned file
bytes.

Expected managed-file failures use the published `FILE_*` registry and one
safe status adapter across typed tools, raw mounts and batch view results.
Unknown I/O causes are logged through canonical normalization and exposed only
as `INTERNAL_SERVER_ERROR`; physical roots and derived host paths never enter a
caller-facing value.

## Consequences

- Applications can opt into safe root ownership without a separate bootstrap
  helper or recursive directory creation.
- Read and write policy cannot drift.
- Exhaustive `StitchErrorCode` consumers must accept the expanded safe file
  code set, and raw native error text now includes its stable code.