# 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](../operations.md#local-state-layout).

## 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](../config.md);
- 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](../cli.md#clean) and
[Operations](../operations.md#cleanup).

## 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`