# Pipeline Execution Ledger Contract

> Status: shared design contract.
> Purpose: define the artifact trust and provenance ledger that every onto
> pipeline must expose or derive across `review`, `reconstruct`, and future
> `evolve`.

## 1. Position

`PipelineExecutionLedger` is a shared runtime concept. It records how a
pipeline produced its artifacts at the unit level so a caller can determine:

- which artifacts are trustworthy;
- which artifacts are untrusted because their producing unit failed;
- which artifacts are blocked because upstream units did not complete;
- which unit is the first incomplete or failed boundary;
- where a later continuation or repair action may safely begin.

Continuation is one consumer of the ledger. The primary purpose is execution
audit, trust boundary inspection, and artifact provenance.

This contract applies to:

- `review`;
- `reconstruct`;
- future `evolve`;
- any later onto pipeline that materializes staged artifacts.

## 2. Ownership

Runtime owns the ledger projection because it observes unit dispatch, validation,
file writes, hashes, and terminal status.

Host LLMs may read the ledger to explain trust boundaries or propose the next
action, but they do not author ledger truth.

Semantic ledgers remain separate:

- `review` semantic ledgers include `finding-ledger.yaml` and
  `issue-ledger.yaml`.
- `reconstruct` semantic or decision artifacts include Seed, confirmation,
  question, failure, revision, and stop-decision artifacts.
- future `evolve` may define design-specification or decision ledgers.

Semantic ledgers explain meaning. The pipeline execution ledger explains whether
the process that produced each artifact can be trusted.

## 3. Minimum Model

Shared ledger shape:

```ts
interface PipelineExecutionLedger {
  schemaVersion: "1";
  pipeline: "review" | "reconstruct" | "evolve" | string;
  sessionId: string;
  sourceRefs: string[];
  units: PipelineExecutionLedgerUnitEntry[];
}

interface PipelineExecutionLedgerUnitEntry {
  unitId: string;
  unitKind: string;
  owner: "runtime" | "host_llm" | "user_or_host_mediated";
  producedArtifactRefs: string[];
  consumedArtifactRefs: string[];
  packetRef?: string | null;
  packetSha256?: string | null;
  outputRefs: string[];
  outputHashes: Record<string, string | null>;
  status:
    | "planned"
    | "completed"
    | "failed"
    | "missing"
    | "skipped"
    | "not_reached";
  trustStatus: "trusted" | "untrusted" | "blocked_by_upstream";
  trustReason: string;
  attemptCount: number;
  lastFailureMessage: string | null;
  upstreamUnitIds: string[];
  downstreamUnitIds: string[];
}
```

Rules:

- `trusted` requires the producing unit to complete and all required output
  artifacts to exist and validate.
- `untrusted` means the unit ran but failed, produced invalid output, or wrote
  artifacts that failed validation.
- `blocked_by_upstream` means this unit's trust cannot be established because an
  upstream required unit is missing, failed, or untrusted.
- `skipped` must include a reason and must not be confused with trusted output.
- A missing optional unit may be `skipped`; a missing required unit is
  `missing` or `blocked_by_upstream`.
- The ledger is derived from existing run artifacts unless a pipeline contract
  explicitly promotes it to a durable artifact.

## 4. Source Inputs

Each pipeline maps its own runtime artifacts into the shared ledger.

| Pipeline | Required derivation sources |
|---|---|
| `review` | `execution-plan.yaml`, `review-run-manifest.yaml`, `execution-preparation/review-context-manifest.yaml`, `execution-result.yaml`, `lens-completion-barrier.yaml`, semantic ledgers when present, and output seats |
| `reconstruct` | `reconstruct-run-manifest.yaml`, `reconstruct-record.yaml`, stage registry, validation artifacts, metrics, stop decision, final output, and output seats |
| `evolve` | future evolve run manifest, target profile, adapter selection, observation/projection artifacts, design specification validation, final disposition, and output seats |

The pipeline-specific source artifacts remain authority. The ledger is a
normalized projection over them.

## 5. Pipeline Mapping

### Review

`review` units include:

- lens units;
- issue artifact units;
- per-lens deliberation units;
- controlled deliberation;
- synthesize;
- record/final-output assembly where runtime treats them as separate stages.

`finding-ledger.yaml` and `issue-ledger.yaml` remain semantic ledgers. They are
inputs for downstream trust once they exist, not replacements for the execution
ledger.

### Reconstruct

`reconstruct` units are runtime projections of the active reconstruct registry
and the TypeScript stage contract. The registry owns artifact, gate, predicate,
readiness, and validator authority; the TypeScript stage id list and ledger
specs are implementation projections that must stay aligned with those registry
authorities and must not introduce independent semantic authority. The current
unit families are:

- material profile and material-profile validation;
- source inventory, source observation, source-observation directive, and
  directive validation;
- per-round source frontier, frontier validation, observation delta, delta
  validation, perspective judgments, exploration synthesis, and observation
  re-entry validation;
- candidate inventory, candidate disposition, and candidate-disposition
  validation;
- `ontology-seed.yaml` and `ontology-seed-validation.yaml`;
- competency questions, competency-question validation, assessment, and
  assessment validation;
- seed confirmation and seed-confirmation validation;
- query proofs, visualization proofs, graph-exploration proofs, and their
  runtime validations when the corresponding downstream capability is claimed;
- failure classification, revision proposal, reconstruct metrics, and their
  validations where applicable;
- reconstruct run manifest and run-manifest validation;
- handoff decision and handoff-decision validation before final output and
  reconstruct-record projection.

Runtime validation units are the trust gates for LLM-authored artifacts. A
semantic artifact can exist but remain untrusted until its validation unit
completes.

### Evolve

Future `evolve` units must begin with:

- target profiling;
- adapter selection;
- material-specific observation or projection;
- design inquiry/specification stages;
- validation and final disposition stages.

No future evolve adapter may bypass the ledger by writing design artifacts
without a producing unit and trust status.

## 6. Status And Result Surfaces

Status tools should expose the ledger, or a bounded projection of it, whenever a
pipeline is prepared, running, halted, or completed.

Result tools should expose enough ledger refs or summary fields for callers to
audit why final artifacts are trusted.

Continuation tools, where implemented, must derive their frontier from the
ledger's trust and completion boundary rather than from ad hoc file existence.

## 7. Durable Artifact Policy

First implementation may keep the ledger as a derived status projection.

Promote a durable root artifact such as `pipeline-execution-ledger.yaml`
only when at least one of these is true:

- external audit needs a stable standalone ledger file;
- continuation attempts need replayable pre/post trust snapshots;
- result artifacts need to cite a ledger ref as part of their trust contract.

If promoted, the durable artifact must still be derived from the pipeline's run
manifest, record, validation artifacts, and output seats. It must not become a
second execution truth.
