Define Agent Machine Local Data Plane and TopoLVM mount contracts

[mdheller]

Context

SourceOS Agent Machine needs a local data/mount plane that works first on Mac/Windows/Linux Podman workspaces and later maps cleanly to TopoLVM-backed local persistent volumes in cluster mode.

The immediate user convention is:

• ~/dev is the shared code/repository mount root.
• ~/Documents/SourceOS/agent-output is the shared agent document output root.
• Future directories may represent Photos, Notes, Reminders, Voice Memos, and other user app bridges, but those should be explicit interface doors and not mounted by default.

TopoLVM should become the cluster-local disk backend analogue for the same mount contract: local disk stays local, placement respects node topology, and mounts are explicit capabilities.

Scope

Add v0 schemas/examples for:

1. AgentMachineLocalDataPlane

   • host root allowlist
   • agent-visible mount paths
   • path class: code | documents | cache | artifacts | media | app-bridge
   • default access mode
   • secrets prohibited flag
   • evidence requirements

2. AgentMachineMountPolicy

   • allowed host paths
   • denied path patterns
   • read/write mode
   • sync/consistency mode
   • owner/uid/gid mapping
   • max size/quota hints
   • retention policy

3. TopoLVMPlacementProfile

   • storage class reference
   • node topology constraints
   • local persistent volume semantics
   • pvc/pv claim hints
   • expansion/snapshot posture
   • evidence mapping back to AgentMachineLocalDataPlane

4. Examples:

   • macOS Podman profile with ~/dev and ~/Documents/SourceOS/agent-output
   • Linux native Podman profile
   • cluster profile using TopoLVM-backed local persistent volumes

Security invariants

• Never mount $HOME wholesale.
• Never mount ~/.ssh, ~/.gnupg, browser profiles, keychains, cloud credentials, token stores, or password stores by default.
• ~/dev is allowed only as an explicit repo/code root and should support repo-level allowlists.
• ~/Documents/SourceOS/agent-output is the default write area for generated documents and reports.
• Photos/Notes/Reminders/Voice Memos/TextEdit-style bridges are future app doors, not default raw filesystem mounts.
• Every mount launch emits a fingerprint/evidence record containing host path, container path, access mode, policy hash, and git ref where applicable.

Acceptance criteria

• Schemas and examples validate under existing SourceOS schema conventions.
• AgentMachineProfile can reference LocalDataPlane and MountPolicy ids.
• TopoLVMPlacementProfile references the same mount semantics without forcing Kubernetes assumptions into Mac/Windows local mode.
• README/schema catalog updated.

Non-goals

• Do not implement Podman mount commands here.
• Do not implement Kubernetes controllers here.
• Do not add real local paths beyond safe example placeholders.
• Do not add secrets, tokens, credentials, or user-specific values.

[mdheller]

Add Browser Downloads mount to the Agent Machine Local Data Plane contract.

Recommended default:

• Host path: ~/Downloads/SourceOS/agent-downloads
• Agent/container path: /workspace/downloads or /browser/downloads depending on profile
• Path class: downloads
• Default access: browser process write/read; agent process read-only unless explicitly elevated
• Execute permission: denied by default for downloaded files where platform/filesystem support allows
• Retention: configurable, default keep until user clears or workspace policy expires

Security posture:

• Do not mount the entire host ~/Downloads by default.
• Do not allow browser downloads to land in repo roots by default.
• Downloaded artifacts should be content-hashed and recorded in evidence.
• Evidence should include filename, content hash, MIME/type if known, source URL/domain with policy-aware redaction, browser session id, and policy hash.
• If a downloaded artifact is later promoted into ~/dev or ~/Documents/SourceOS/agent-output, that should be an explicit copy/promote action with its own evidence record.

Schema update request:

• Add downloads to path class enum.
• Add downloadPolicy to BrowserDoor / LocalDataPlane relationship.
• Add example mount for ~/Downloads/SourceOS/agent-downloads in the macOS Podman profile.

[mdheller]

Contract-first slice landed on main.

Added schemas:

• schemas/AgentMachineLocalDataPlane.json
• schemas/AgentMachineMountPolicy.json
• schemas/TopoLVMPlacementProfile.json

Added examples:

• examples/agent_machine_local_data_plane_macos.json
• examples/agent_machine_mount_policy_default.json
• examples/topolvm_placement_profile_agent_machine.json

Added documentation:

• docs/contract-additions/agent-machine-local-data-plane.md

Design decisions now encoded:

• ~/dev is the explicit code/repo root.
• ~/Documents/SourceOS/agent-output is the explicit generated document/report root.
• ~/Downloads/SourceOS/agent-downloads is the scoped browser downloads root.
• Whole $HOME mounts are denied.
• Sensitive paths such as .ssh, .gnupg, browser profiles, keychains, cloud credential dirs, token stores, and password stores are denied by default.
• TopoLVM is modeled as topology-aware node-local persistent volume storage, not cross-node shared storage.
• Downloads promotion into code/docs space requires explicit evidence.