notarius/docs/roadmap/workspace.md

# Workspace Roadmap

Notarius should gain a single configurable workspace root for application-owned
local state. The workspace exists only to support enabled workspace features;
ordinary runs should not write workspace files by default.

The workspace is distinct from durable output:

- durable output is the user-requested final product of a run;
- the workspace is application-owned local state for diagnostics, resumable
  checkpoints, and development/debug workflows.

Within the workspace, diagnostics, checkpoints, and debug artifacts should use
separate subdirectories because they have different identity and lifecycle
models.

## Target Configuration

Workspace behavior should be configured under a dedicated top-level object:

```yaml
workspace:
  directory: /var/lib/notarius
  diagnostics:
    enabled: true
    retention: auto
  resume:
    enabled: false
  debug:
    enabled: false
```

Policy:

- `workspace.diagnostics.enabled` defaults to the current diagnostics behavior
  during migration.
- `workspace.resume.enabled` defaults to `false`.
- `workspace.debug.enabled` defaults to `false`.
- no checkpoint or debug files are written when those features are disabled.
- `/var/lib/notarius` should be the standard production recommendation in docs
  and examples.
- local development docs may recommend a project-local path such as
  `./.notarius/workspace`.

`workspace.directory` should become the single configured root for Notarius local
state. Existing `diagnostics.work_dir` behavior should be migrated carefully for
backward compatibility, but the long-term configuration model should avoid two
separate roots for application-owned local state.

## Workspace Layout

The workspace root should contain separate subtrees:

```text
<workspace.directory>/
  diagnostics/
  checkpoints/
  debug/
```

Diagnostics remain run-id based. They are invocation history and should preserve
the existing diagnostics retention model:

```text
<workspace.directory>/
  diagnostics/
    <run-id>/
      invocation.json
      effective-config.json
      resolved-pipeline.json
      resolved-references.json
      run-manifest.json
      warnings.json
      run-report.json
      error.log
```

Checkpoints should be deterministic and should include enough identity material
to prevent unsafe reuse across incompatible runs:

```text
<workspace.directory>/
  checkpoints/
    <pipeline-id>/
      <input-key>-<source-digest-prefix>/
        <pipeline-digest-prefix>/
          source/
          chunk/
          extract/<lane-id>/
          merge/<lane-id>/
          normalize/<lane-id>/
```

Checkpoint identity should account for:

- resolved pipeline ID;
- resolved pipeline digest;
- input adapter key;
- source/input digest;
- selected lanes and runtime overrides that affect execution;
- reference digests;
- prompt, schema, and profile provenance when not already captured by the
  resolved pipeline digest.

Debug output should be run-id based like diagnostics, because debug traces are
development artifacts from a specific invocation rather than resumable state:

```text
<workspace.directory>/
  debug/
    <run-id>/
```

Human-readable path segments are useful, but content hashes should be
authoritative for correctness. The exact path shape may change during
implementation, but checkpoint identity must be stable, deterministic, and safe
to compare across runs. Diagnostics and debug output do not need deterministic
resume identity because they are per-invocation artifacts.

## Stage Ownership

Stage manifests should be stage-owned. There should not be a root-level manifest
that summarizes all stages.

Rationale:

- stage manifests are the authoritative state for the stage that wrote them;
- avoiding a root summary prevents duplicate state from drifting;
- stage-local manifests make partial writes, failure recovery, and future stage
  invalidation easier to reason about.

Each stage manifest should record enough information to determine whether its
outputs can be trusted for resume:

- workspace schema/version;
- stage name and lane ID when applicable;
- module key and relevant module provenance;
- dependency fingerprints and input digests;
- status such as pending, running, succeeded, succeeded with rejections, failed,
  or invalidated;
- output content digests;
- validation status and rejection summaries where relevant;
- timing metadata when useful and non-sensitive.

## Checkpoint Output

When `workspace.resume.enabled` is enabled, Notarius should write under the
`checkpoints/` subtree. Checkpoints should contain only artifacts required to
resume safely.

Checkpoint artifacts may include:

- source document checkpoint;
- chunk collection checkpoint;
- accepted extract outputs;
- rejected extract records;
- merge output;
- normalize output;
- stage manifests with dependency fingerprints and output digests.

Checkpoint output should avoid raw prompts, raw references, raw LLM request
payloads, and other sensitive development artifacts unless they are strictly
required for safe resume. Prefer digests and provenance over copying sensitive
inputs.

Checkpoint writes should be atomic at the file level. Partial or interrupted
writes must not be mistaken for successful stage completion.

## Debug Output

When `workspace.debug.enabled` is enabled, Notarius should write under the
`debug/<run-id>/` subtree. Debug artifacts are useful for inspection but not
required for resume.

Debug artifacts may include:

- rendered prompt inputs;
- structured LLM request and response traces;
- raw model responses;
- copied reference content;
- copied source snippets;
- intermediate raw payloads;
- validator request/response details.

Debug output is explicitly sensitive. Documentation should warn that debug
workspace data may contain source material, references, prompts, and model
outputs. Debug output should remain disabled by default.

`workspace.debug.enabled` and `workspace.resume.enabled` should be independent.
Enabling debug should not imply resume, and enabling resume should not imply
debug.

## Resume Semantics

Resume should be explicit at first, for example through a future `resume` command
or a `run --resume` flag. Plain `run` should not silently skip completed stages
in the initial workspace feature.

Before reusing a checkpoint, Notarius should verify that:

- the workspace schema/version is supported;
- the checkpoint stage manifest is complete and successful;
- dependency fingerprints match the current invocation;
- referenced checkpoint files exist and match recorded digests;
- selected lanes and runtime overrides are compatible with the checkpoint.

Rejected extract outputs should be treated as recorded stage outcomes, not
framework failures. Under current pipeline policy, rejected outputs do not pass
to downstream stages.

## Boundaries

Workspace writing should be framework-owned. Concrete modules should not write
directly to workspace paths.

If modules need to expose debug material later, they should return logical
artifacts through framework contracts and let framework or CLI code perform path
validation, redaction policy, and writes.

Workspace state should preserve existing Notarius boundaries:

- provider plumbing remains behind LLM runtime contracts;
- prompt ownership remains with modules and prompt asset helpers;
- diagnostics remain per-run invocation artifacts under the workspace root;
- output modules continue to own final durable output encoding;
- secrets and sensitive payloads are not written unless an explicit debug policy
  enables them.

## Deferred Work

Default-idempotent `run` behavior with a `--force` override, remote workspace
storage, workspace garbage collection, archival policy, and cross-machine resume
are deferred.