# Internal: Workspace

## Purpose
Define local session layout, run-local stage layout, and cleanup guardrails.

## Canonical Session Layout
Session root:
- `{workspace.root}/work/{campaign}/{session_id}`

Core directories/files:
- `inputs/`
- `audio/`
- `transcripts/`
- `artifacts/`
- `reports/`
- `logs/`
- `config/`
- `current/`
- `runs/`
- `previous/`
- `manifest.json`
- `.lock`

`previous/` reserved files:
- `previous/manifest.json`
- `previous/artifacts/**`

## Run-Local Stage Layout
When run context is available, stages use:
- `runs/{run_id}/{stage}/outputs/`
- `runs/{run_id}/{stage}/logs/`
- `runs/{run_id}/{stage}/reports/`
- `runs/{run_id}/{stage}/config/`
- `runs/{run_id}/{stage}/scratch/`

Run-local outputs are materialized back into canonical session paths before stage success.
`previous/**` writes are never redirected to run-local output paths.

## Locking
`artifacts.LocalStore` enforces single-writer session lock via `.lock` file (`ErrLockConflict` on contention).

## Cleanup Semantics
Automatic post-publish cleanup (`runPostArchiveCleanup`):
- only runs when publish actually executed and succeeded;
- requires `uploaded=true` and `current_pointer_written=true` metadata;
- respects `pipeline.spool.delete_audio_after_publish` and `pipeline.workspace.cleanup_after_publish`;
- refuses unsafe deletes (root delete, out-of-root delete, symlink paths).

Manual clean command:
- `clean <session_id>` removes session work and spool subtree.
- `clean --all` removes all workspace work and spool children.
- durable cache is preserved unless `--clear-cache` is requested.

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