From d2afa9dbd251e4e4a8ef518d6d27dc950b79c4b4 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 11 Sep 2026 15:04:54 +0000 Subject: [PATCH] Document deployment-managed cache permissions --- docs/config.md | 5 ++++ docs/internal/state.md | 14 +++++++++-- docs/operations.md | 44 ++++++++++++++++++++++++++++++---- docs/policy/architecture.md | 9 +++++++ docs/roadmap/implementation.md | 2 ++ 5 files changed, 67 insertions(+), 7 deletions(-) diff --git a/docs/config.md b/docs/config.md index 43e635b7..54de1b62 100644 --- a/docs/config.md +++ b/docs/config.md @@ -69,6 +69,9 @@ Built-in defaults are: An empty cache directory in YAML deliberately selects the corresponding per-user root. An explicit empty output or debug directory is invalid. +Selecting a chunk-plan or checkpoint directory does not configure filesystem +access policy. Cache permissions come from deployment provisioning, process +umask, setgid inheritance, and default ACLs; see [Operations](operations.md#cache-provisioning). ## PromptKit Profiles @@ -200,6 +203,8 @@ through **total_llm**. When omitted, it is recalculated from the effective **cache.chunk_plans.mode** accepts **auto**, **bypass**, or **refresh**. **cache.checkpoints.enabled** is a boolean. The CLI can override the output directory and chunk-plan mode for one run; see [CLI reference](cli.md#run). +Cache directory fields select only locations; Notarius has no cache permission +field or environment override. ## Pipelines diff --git a/docs/internal/state.md b/docs/internal/state.md index 6be86bad..86492735 100644 --- a/docs/internal/state.md +++ b/docs/internal/state.md @@ -32,11 +32,18 @@ owned by the [Accepted Chunk Map contract](../integrations/chunk-map.md). `internal/framework/chunkplan` owns source-addressed plan storage, validation, and atomic publication. Its store is constructed only when the selected mode is -not `bypass`. +not `bypass`. It preserves rooted entry checks while creating new cache roots +and source-digest directories with requested mode `0777`, then creates an +atomic temporary file through rooted `O_CREATE|O_EXCL` with requested mode +`0666` before sync and rename. `internal/framework/checkpoint` owns checkpoint identity, manifests, payload codecs, loader, and recorder. The CLI constructs a recorder whenever checkpoint recording is enabled and constructs a loader only for a `--resume` invocation. +The recorder writes manifest and payload JSON through +`fileio.WriteJSONWithProcessPermissions`, whose confined atomic writer creates +new directories with requested mode `0777` and temporary files with requested +mode `0666` before publication. Identity incorporates explicit stable semantic fingerprints collected from prepared modules and validators in addition to configuration, input, references, runtime overrides, observed LLM profiles, and the LLM runtime's @@ -86,7 +93,10 @@ and debug-summary JSON. canonical operator-facing reason-code reference. `internal/core/fileio` provides confined atomic file writes used by state -collaborators. The chunk-plan store retains its stronger entry validation. +collaborators. Its exact-mode writer remains available to output and debug +callers; its process-permission writer is used by checkpoints. The chunk-plan +store retains its stronger rooted entry validation. [Operations](../operations.md#cache-provisioning) +owns cache mode and provisioning guidance. The CLI constructs selective-recomputation policy from resolved generated artifact dependencies. It forces the selected step and transitive consumers, diff --git a/docs/operations.md b/docs/operations.md index e143e80f..d673bc4f 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -50,11 +50,45 @@ directory selects a per-user root: The field definitions and configuration examples are in [Configuration](config.md). On supported Unix systems, output directories and files are created with -requested modes **0755** and **0644**. Chunk-plan, checkpoint, and debug -directories and files use **0700** and **0600**. The operating system's umask -may impose stricter output modes. Cache and debug roots may contain sensitive -source-derived data, so provision them for one trusted account or service. An -output bundle can also contain source content when its JSON output enables +requested modes **0755** and **0644**; debug directories and files use +**0700** and **0600**. The operating system's umask may impose stricter output +or debug modes. Chunk-plan and checkpoint caches instead request maximum modes +of **0777** for new directories and **0666** for new files, including atomic +temporary files. The kernel applies the service's umask and applicable default +ACLs when those entries are created. + +## Cache Provisioning + +Cache locations select where Notarius writes, not who can access them. A +private service can use a restrictive umask: + +~~~sh +umask 0077 +notarius run example --config /etc/notarius/config.yml --input /srv/input.txt +~~~ + +A trusted-group deployment can provision a setgid cache root and use a +group-oriented umask (or an equivalent default ACL): + +~~~sh +install -d -m 2770 -g notarius-operators /srv/notarius/chunk-plans /srv/notarius/checkpoints +umask 0007 +notarius run example --config /etc/notarius/config.yml --input /srv/input.txt +~~~ + +Setgid and default ACLs control inherited group ownership and access policy; +Notarius does not copy a parent directory's literal mode bits. Cache state is +reconstructible but can contain source-derived data, so operators own its +access and retention policy. Existing cache inodes retain their prior modes +after an upgrade. Recreate a cache beneath correctly provisioned parents, or +stop writers and perform a deliberate administrative migration when a +whole-tree change is required. + +Cache publication remains atomic and stored records remain validated. Those +guarantees do not add cross-process locking or transactional coordination for +simultaneous writers to one checkpoint identity. + +Output bundles can also contain source content when JSON output enables evidence publication. Apply an appropriate umask and output-root access policy before enabling that option; the requested output modes alone may not be suitable for transcript-bearing bundles. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index c07ea8db..290a72c9 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -293,6 +293,15 @@ an invocation that explicitly requests resume. Debug is never a cache input and is never created without an explicit request. Pipeline modules receive collaborator interfaces and never physical roots. +Deployments own cache access policy. Cache writers request conventional maximum +creation modes and let the process umask, setgid inheritance, and default ACLs +determine effective access. Notarius owns the separate safety boundary: +confined paths, symlink rejection, atomic publication, validation, and +recovery. It does not chmod, chown, chgrp, or migrate cache entries to impose +an application policy. This rule applies to chunk-plan and checkpoint cache +only; output and debug retain their separate contracts. [Operations](../operations.md) +owns deployment provisioning and retention guidance. + Only accepted, completely validated producer output is reusable checkpoint or chunk-plan state. Rejected, structurally invalid, and validation-incomplete results cannot become cache or checkpoint inputs, even when a diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index d0c24c88..cad483cf 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -244,6 +244,8 @@ prompt. ## Stage 4: Update Canonical Documentation +**Completed:** 2026-09-11 + ### Goal Make the implemented behavior discoverable without duplicating volatile