Extraction runs: the durable run model

[jimador]

PR 6 of the extraction-integrity train (refs #67 — the model half), stacked on #94. The durable extraction-run record, as pure JVM value types. ExtractionRun is keyed by (ContextId, ExtractionRunRef) and carries profile, ordered source revisions, pass, parent/superseded refs plus a denormalized root-run ref (OpenLineage's ParentRunFacet pattern — a whole-lineage lookup becomes one indexed read), experiment/cohort refs, prompt/schema/metamodel fingerprints, runtime identity, status, timing, counts, and bounded failures. Requested and observed model facts are separate types with disjoint fields, so a guessed provider-effective value has nowhere to live. Invocation identity is the ordinal in a call plan fixed before any call fires; attempts number retries; completion order never mints. Opaque pseudonymous refs carry actor/request/session identity with serialized-row privacy tests.

Changed in this review round:

• Failures speak a closed vocabulary. ExtractionFailure has no String parameter, property or field anywhere in its reachable shape and no factory taking a Throwable: code (11 values), stage, a validated providerStatus, one typed measure with its unit, at, and the invocation it names. detail, fromThrowable and the sanitize/cause-chain helpers are removed, so prompt content, PII, credentials and protected text have nothing shaped to hold them and cannot reach durable storage through this type.
• Run recording aligns with the source-revision contract. The revision bound this type imposed is gone — a run accepts whatever SourceRevisionRef accepts, so extraction and revision queries can no longer succeed where run recording then fails.
• The lineage root is derived. The constructor is private and childOf derives the root from the parent's own lineage, so a root that contradicts its parent has no public path in; the KDoc records the reflection residual honestly.
• metamodelFingerprint keeps its field and its KDoc names its one writer: the extraction coordinator, resolving the host's DeclaredSchemaSource — per the decision that per-proposition schema attribution answers through run lineage.

Breaking changes: none. New types only. The failure-vocabulary rework reshapes types introduced earlier in this same unreleased train; no released surface moves.

Opt-in and status: EXPERIMENTAL — every type carries @ApiStatus.Experimental. Nothing here executes; the store contract, the Drivine store, and lineage stamping follow as #98, #99 and #101.

erDiagram
    ExtractionRun ||--o{ ExtractionInvocationRecord : "invocations, identity fixed before any call"
    ExtractionRun ||--o{ ExtractionFailure : "bounded, typed vocabulary, no free text"
    ExtractionRun ||--|| ExtractionRunLineage : "runRef, root, parent, pass"
    ExtractionRun }o--|| ExtractionContentProfileRef : "profile"
    ExtractionRun }o--o{ SourceRevisionRef : "ordered source revisions"
    ExtractionFailure }o--o| ExtractionInvocationRecord : "may name only an attempt the run records"

Loading

The denormalized root is what makes a whole-lineage lookup one indexed read.

[igordayen]

@jimador - looks vey good, few comments to consider, thanks

[igordayen]

@jimador - looks good, subject to rebase. thanks