Align internal documentation and maintained examples

docs/internal/workspace.md

@@ -1,57 +1,62 @@
 # 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}`
+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).
 
-Core directories/files:
-- `inputs/`
-- `audio/`
-- `transcripts/`
-- `artifacts/`
-- `reports/`
-- `logs/`
-- `config/`
-- `current/`
-- `runs/`
-- `previous/`
-- `manifest.json`
-- `.lock`
+## Path Ownership
 
-`previous/` reserved files:
-- `previous/manifest.json`
-- `previous/artifacts/**`
+`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
-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.
+`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 single-writer session lock via `.lock` file (`ErrLockConflict` on contention).
+
+`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;
-- respects `pipeline.spool.delete_audio_after_publish` and `pipeline.workspace.cleanup_after_publish`;
+- consumes the resolved cleanup policy described in
+  [Configuration](../config.md);
 - 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.
+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`