# Data lineage

Data lineage connects a displayed result to the sources, versions, assumptions, calculation, and human actions that produced it. Klineo preserves that connection so a later refresh does not silently change the evidence used for an earlier study or decision.

Use lineage to answer three questions: **What was observed? What was calculated from it? What was authorized and verified afterward?** Those are separate claims.

## Read an evidence record

Different resource types expose different fields. Inspect the fields returned by that operation's schema rather than assuming every artifact has the same envelope.

| Field or concept | What it tells you | What it does not establish |
| --- | --- | --- |
| Chain, asset, pool, or subject identity | Which market or resource the evidence concerns | Ownership, approval, or eligibility for another chain |
| Block number and block hash | The chain state used for a pinned observation | That all providers or offchain facts were independently corroborated |
| Block timestamp | Time recorded by the chain | When your request or analysis finished |
| Read time | When the source read completed | That the result was persisted or remains current |
| Recorded time | When a saved record was persisted, when supplied | A new observation of the chain |
| Provider identity and generation | Which configured source generation supplied the observation | Continuous provider certification |
| Resource version | The exact aggregate generation selected for a read or command | That the generation will remain the current head |
| Input, content, or artifact hash | A commitment to the stated payload or artifact | Accuracy or completeness of every source and assumption |
| Source cutoff and coverage | Which evidence was available to the task and which gaps remain | Evidence outside that captured scope |
| Engine or model version and seed | How a modeled result was produced | A guarantee of future performance |
| Signature and publication state | The authorization and integrity checks in the stated publication workflow | A general guarantee about the issuer or market |

A public observation can explicitly return `recordedAt: null`. That means the response itself did not persist the evidence. Save the observation through the supported workspace flow if your analysis needs a durable reference.

## Preserve identity and units

Store source IDs together with their returned versions and hashes. A token address alone is insufficient: chain identity, token precision, pool identity, and source block determine what the values describe.

Financial amounts use atomic integer strings. For example, `"1250000"` means 1,250,000 indivisible units; converting it to a human amount requires the verified precision for that asset. Fixed-point ratios can use pips, with `1_000_000` representing the full ratio in the relevant contract. Interpret each field using its schema and unit definition.

Keep token, quote, and fiat units separate. A quote-atomic amount is not a dollar amount without the additional valuation evidence that the resource actually supplies. An unverified unit label must remain unverified when you export or chart it.

## From observation to saved analysis

A public project read returns the supported market evidence and its gaps. Saving captures a private observation generation for the selected organization. Refreshing the project changes its current observation while retaining earlier generations.

An investigation or Decision Pack references the selected observation. Its historical reference remains readable after a project refresh, but it does not become current by inheritance. Compare the captured source with the project's current head when deciding whether a new review is needed.

Decision Packs preserve immutable human review versions. Their assumption notes explain the human context; they are not automatically quantitative simulation inputs. A pack can retain public evidence, supported Research candidate evidence, or a historical treasury projection under the relevant pack scope. Each reference carries its own limitations.

## From inputs to a study

A study captures a specific input document, assumptions, source generation, engine version, and the required seed or replay context. The deterministic engine produces the output and artifact commitments for that input.

Keep these distinctions visible when presenting study results:

- **Observed evidence** describes the captured source state.
- **Declared assumptions** describe inputs chosen or accepted for the model.
- **Calculated results** describe what the stated engine produces from those inputs.
- **AI inference or hypothesis** describes explanatory or proposed context with its stated grounding.

A digital-twin scenario is hypothetical. A historical replay has its own source coverage and model scope. Research comparisons retain failed and ineligible trials, and ranking depends on a valid comparable baseline. Missing costs remain unknown; do not convert them to zero. Subtracting two marginal percentiles does not establish a paired-path difference.

Use a saved result's identity to open its exact study and methodology. A successful task admission is not the study artifact, and a terminal task state is not by itself proof that a validated report is available.

## Versions and safe commands

Selected-record mutations use the exact resource version required by the endpoint, commonly through `If-Match`. A command reviewed against an older generation should not automatically approve a newer head. On a version conflict, reload the resource and review the new generation before issuing a new action.

Idempotency keys identify a particular command attempt. For an uncertain response, retry the same authorized command with its original key and exact payload according to that operation's contract. Reusing the key for changed inputs is not a new review. Current membership and authorization still apply when recovering a command receipt.

An immutable version records what the actor saw and did at that point. Supersession points to a later record while preserving the earlier one. Currentness, lifecycle state, and content identity can change independently; a lifecycle-only update does not always mean the economic assumptions changed.

## From approval to execution evidence

A financial proposal binds its required source snapshot, study, policy, action, limits, nonce, and expiry. Human approvals record governance decisions. A Safe signature authorizes the issuer's packet through the separate Safe workflow.

Execution evidence then advances through distinct stages:

| Stage | Meaning |
| --- | --- |
| Submitted | A transaction identity or submission record has been registered |
| Included | A matching transaction has been observed in a block |
| Finalized | The chain observation satisfies the configured finality requirements |
| Reconciled | Required transaction and resulting-state checks match the expected action |
| Attributed | The applicable observed outcome and costs have been materialized for analysis |

Replacements, failures, and reconciliation mismatches retain their own evidence. A transaction hash does not establish a successful financial outcome. A chain reorganization can invalidate dependent observations before finality; the system must rebuild the affected projections rather than preserve a false success.

## From private report to public proof

Saved analyses and finalized outcome reports have different scopes. An analysis can contain hypothetical studies or partial public evidence. A finalized outcome report refers to the reconciled financial evidence within its stated period and coverage.

Publication requires the issuer-controlled disclosure and authorization workflow. A public proof response contains the permitted report material, source commitments, action evidence, and limitations. A Liquidity Passport has its own signature, validity, freshness, and supersession checks.

For a public artifact, verify the requested slug, artifact identity, disclosure scope, signature or trust-anchor state, source coverage, and applicable validity period. Download and retain the supplied verification bundle when your integration needs independent review. A hash establishes integrity of the referenced content; it does not turn a partial source into complete evidence.

## Integration checklist

1. Bind requests and stored private records to the intended organization.
2. Keep exact IDs, resource versions, hashes, chain identity, and units together.
3. Show source timestamps, coverage, gaps, and model assumptions beside derived values.
4. Preserve historical references when a current source refreshes.
5. Treat approval, submission, finality, reconciliation, and publication as separate states.
6. Retain failure and unknown states when exporting data or building a dashboard.

See [Architecture](/platform/architecture) for the authority boundaries that enforce this workflow and [Platform overview](/platform/overview) for the application routes that expose it.