Extraction profiles: versioned identity through compatible entry points

[jimador]

PR 5 of the extraction-integrity train (closes the entry-point half of #66; refs #67), stacked on #93. ExtractionRequest is the entry-point surface: one value object carrying everything a caller says about an extraction beyond the text and the user — sourceLocator, sourceRevision, profile. Each entry point is exactly two declarations: the signature main publishes, byte-identical, plus one overload taking the request. ExtractionContentProfileRef names a stable name+version identity for source-independent extraction behavior; opaque by design — DICE carries the identity, the host authorizes and binds what it names, and profiles select no provider, model, or credential. The request validates its own coupling in init: a revision requires a locator whose key it matches, so a mismatched pair can never reach an entry point.

Changed in this review round:

• The request object replaces the widening overloads. All six in-train wide overloads are deleted; rememberTextFromSource and rememberFileFromSource no longer exist as names, so the wide forms never ship in a release and Return typed product outcomes for batched and linked extraction passes #69 has nothing to deprecate. The next dimension extraction learns about arrives as a field on the request while the entry-point signatures stay put.
• Profile is carried once. The request is the single entry-point door onto SourceAnalysisContext; the context keeps profile as the downstream read point — a host PropositionExtractor receives the whole context on every extract(chunk, context) call, and the run record reads it there once the coordinator lands.
• No no-op parameters. The currentRun parameter that was accepted and then dropped at persistence is removed here; a reflection sweep fails the build if any request member mentions a run before the consuming write exists. It returns as the request's fourth field on Extraction runs: proposition lineage #101, together with the lineage write that consumes it.

Breaking changes: none — including for subclasses. Every pre-request entry-point signature stays present, open, and reached, pinned four ways: the declared descriptor set, non-finality assertions, a subclass override called on every published arity (positional and named), and Java interop with @Override compile proofs. New constructor parameters follow the stated Kotlin-synthetics boundary.

Opt-in and status: EXPERIMENTAL (@ApiStatus.Experimental). The trigger is passing an ExtractionRequest; legacy calls behave byte-identically, and ExtractionRequest.NONE dispatches exactly as the legacy call it resembles, so a subclass overriding only the six-argument rememberText still intercepts file ingestion.

The dispatch shape — every call funnels to one terminal method, and legacy overrides stay reached:

flowchart TD
    A[legacy rememberText] --> W[rememberText with request]
    B[legacy rememberFile] --> X[rememberFile with request]
    X --> W
    E[async event paths] --> W
    W --> C[buildContext]
    C --> D[SourceAnalysisContext: locator, revision, profile, perspective, schema, tenant]
    S[a subclass override of a legacy signature stays reached] -.-> X

Loading

Overridable and reached are different claims, so they are tested separately.

[igordayen]

@jimador - looks good, minor inquiries on data classes validation / usage. thanks

[igordayen]

is data class validation on init standard practice?

Suppose, theoretically, a secondary constructor were added; would init be executed?

If the pattern gets used in many places, perhaps introduce ValidationAware interface?

[jimador]

init runs for every construction path. A secondary constructor in Kotlin has to delegate to the primary one, and the primary's init blocks run as part of that delegation, so there is no constructor that skips it. copy() goes through the primary constructor too. That is why the check lives there and not in a factory: there is no way to get an instance that was not checked.

On a ValidationAware interface: what would it add? The check has to run at construction to keep an invalid instance from existing at all; an interface method a caller has to remember to invoke is weaker than that. Where the same rule shows up in several types (the bounds in SourceIdentityBounds are the case today) the shared piece is the rule, and each type's init calls it. Happy to revisit if a use case needs validation after construction.

[igordayen]

if im not mistken sourceLocator has been already validated in init

[jimador]

Different job. init checks that a revision, when present, names the same source the locator does. The ?.let here is null handling: sourceLocator is optional on the request, and the context only gets one when the caller supplied one. Nothing is validated twice.

[igordayen]

@jimador - looks good, subject to rebasing, thanks