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.

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
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/app/cleanup_targets_test.go, internal/app/post_publish_cleanup_test.go

2.3 KiB Raw Blame History