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.

1.7 KiB Raw Blame History