Internal: Workspace

Purpose

Explain the helpers that construct local session and run paths, coordinate single-writer access, and confine cleanup. The authoritative physical layout and retention workflow belong in Operations.

Path Ownership

internal/artifacts owns canonical session, run, spool, cache, and previous-cache path construction. SessionPathsFor provides the session-scoped path model, and layout creation goes through EnsureLayoutFor. Callers should consume those helpers instead of rebuilding relative paths.

internal/pathsafe and application cleanup helpers enforce confinement for relative destinations and deletion targets.

Run-Local Stage Layout

internal/stage/run_local.go maps stage outputs and diagnostics into an invocation-scoped layout. Successful outputs are validated and atomically materialized into canonical session paths before stage success. Managed previous-session cache paths remain session-durable and are never redirected into run-local output space.

Extraction uses run-local receipt, stderr, and output-root helpers, then promotes the validated external bundle to the unique immutable Notarius bundle path supplied by internal/artifacts. internal/fileops.PromoteDirectory copies only regular files and directories to a same-filesystem temporary sibling and atomically renames it without following symlinks or replacing an existing destination. Exact physical paths belong in Operations.

Locking

artifacts.LocalStore enforces the single-writer session lock via .lock (ErrLockConflict on contention).

Cleanup Semantics

Automatic post-publish cleanup:

only runs when publish actually executed and succeeded;
requires uploaded=true and current_pointer_written=true metadata;
consumes the resolved cleanup policy described in Configuration;
refuses unsafe deletes (root delete, out-of-root delete, symlink paths).

Manual cleanup uses the same scoped-target checks. Invocation syntax and exact deletion scope belong in CLI and Operations.

Invariants

campaign-aware session root is mandatory.
manifest-driven stage state is durable across runs.
cleanup guardrails prevent destructive root/out-of-scope deletion.

Implementation And Tests

Path model and local store: internal/artifacts/paths.go, internal/artifacts/local.go
Run-local materialization: internal/stage/run_local.go
Immutable bundle promotion: internal/fileops/directory.go
Cleanup confinement: internal/app/cleanup_targets.go, internal/app/post_publish_cleanup.go
Tests: internal/artifacts/paths_model_test.go, internal/artifacts/local_test.go, internal/stage/run_local_test.go, internal/fileops/directory_test.go, internal/app/cleanup_targets_test.go, internal/app/post_publish_cleanup_test.go

2.9 KiB Raw Blame History