notarius/docs/adr/0017-defer-cache-access-policy-to-deployment.md

ADR-0017: Defer cache access policy to the deployment

Status: Accepted Date: 2026-09-11

Context

Canonical chunk plans and invocation checkpoints are reconstructible cache state. They may include source-derived content, so access and retention matter, but Notarius cannot determine whether a deployment needs a private cache or a cache shared by a trusted group. The current application-enforced 0700 and 0600 modes prevent ordinary Unix provisioning from making that choice.

ADR-0005 governs canonical chunk-plan reuse, while ADR-0006 established the output, cache, and debug separation refined by ADR-0007. None of those decisions requires Notarius to own exact cache access modes.

Decision

Deployments own cache access policy through provisioned directories, process umask, setgid inheritance, and default ACLs. Notarius requests conventional maximum creation modes for cache entries and leaves the kernel to select their effective permissions.

Notarius continues to own confined paths, symlink rejection, validation, atomic publication, cleanup, and recovery. Those correctness boundaries are independent from deciding which accounts may access cache state.

Source-derived cache contents can be sensitive. Operators own their access and retention policy, while API credentials remain outside cache payloads under the existing secret boundary. Existing cache inode modes are not migrated automatically.

This decision does not supersede ADR-0005, ADR-0006, or ADR-0007.

Alternatives considered

• Continue enforcing private 0700 directory and 0600 file modes. This makes one deployment choice for every operator and prevents trusted-group provisioning.
• Add configurable Notarius permission modes or a private/group cache setting. This preserves application ownership of a deployment concern and expands the public configuration surface without a durable policy reason.
• Recursively converge existing cache ownership, modes, or ACLs. This would make upgrades mutate operator-managed state and cannot safely infer an intended policy.

Consequences

Operators can use a restrictive umask for private cache state or provision a setgid/default-ACL cache root for trusted-group access. They must deliberately recreate or administratively migrate pre-existing cache trees when their existing modes do not match the desired deployment policy.

Notarius does not add user or group management, ACL mutation, permission configuration, or recursive cache migration. Output and debug permission contracts remain separate from this decision.