narratio/docs/development/workspace-implementation-plan.md

Workspace Architecture Implementation Plan (Status)

This document tracks the implemented workspace architecture and remaining work for v1.0.

Current Architecture (Implemented)

Narratio now uses a canonical campaign-aware local layout:

{workspace.root}/work/{campaign_id}/{session_id}/
  manifest.json
  current/
    manifest.json
    run_id.txt
  inputs/
  transcripts/
  artifacts/
  reports/
  logs/
  config/
  runs/
    {run_id}/
      manifest.json
      {stage}/
        outputs/
        logs/
        reports/
        config/
        scratch/

Core behavior:

• Session manifest remains the skip/resume source of truth.
• Each invocation creates a run manifest at runs/{run_id}/manifest.json.
• Stage execution writes run-local artifacts and promotes durable outputs to canonical session paths.
• Archive uploads run records under runs/{run_id}/, applies promotion rules, then publishes current/manifest.json and current/run_id.txt.
• Analyze input resolution uses centralized artifact IDs with alias support.
• Forced upstream reruns mark downstream succeeded stages stale so later runs do not skip stale outputs.

Section 4 Sequence Status

Step 1: Campaign-aware session path model

Status: complete.

Implemented:

• Campaign-aware session and run path helpers.
• Campaign-aware artifact-store layout APIs.
• Canonical session manifest pathing under work/{campaign}/{session}.

Step 2: Session manifest + run manifest scaffolding

Status: complete.

Implemented:

• Invocation-scoped run manifest type and store methods.
• Runner creates/saves run manifests per invocation.
• Session manifest remains authoritative for idempotent stage skipping.

Step 3: Run-local stage execution + promotion

Status: complete.

Implemented:

• Run-local stage directory layout under runs/{run_id}/{stage}.
• Shared helpers for run-local output mapping and promotion to canonical durable paths.
• Producer run provenance recorded on durable artifact outputs.

Step 4: Archive alignment

Status: complete.

Implemented:

• Canonical run-root/session-root resolution.
• Deterministic run-file collection and promotion source resolution.
• Current-pointer publication ordering retained (current/manifest.json then current/run_id.txt).

Step 5: Artifact registry/resolver (analyze first consumer)

Status: complete.

Implemented:

• Central artifact resolver with canonical IDs:
  • narratio.transcript.merged
  • narratio.transcript.polished
  • narratio.transcript.full
  • narratio.transcript.trimmed
  • narratio.bounds.session
  • narratio.artifact.session_recap
• Backward-compatible aliases:
  • processed_transcript
  • normalized_transcript
  • trimmed_transcript
• Analyze stage switched to resolver-based source resolution.

Step 6: Minimal downstream invalidation for forced reruns

Status: complete.

Implemented:

• Deterministic downstream invalidation based on canonical stage order.
• On forced successful rerun of stage X, downstream succeeded stages are marked stale.
• Resume and non-forced runs naturally re-execute stale stages.

Step 7: Legacy layout migration strategy

Status: intentionally skipped.

Decision:

• Automatic migration and legacy fallback compatibility are intentionally not implemented.
• The codebase targets canonical-only local layout behavior.
• Legacy local workspace state, if present, should be recreated or migrated manually outside Narratio.

Remaining Work (v1.0)

No required workspace/run-history migration steps remain from Section 4.

Possible future enhancements (non-blocking):

• Full checksum/input-graph stale detection.
• Optional retention-policy expansion for run-history cleanup.
• Broader artifact-resolver adoption across additional stage consumers.