Provenance & lineage

Geopera records lineage at the moment data is created — not as an afterthought, a log, or a best-effort background job. When an operation produces an artifact, the lineage record is written in the same transaction that creates the artifact. If the lineage can’t be recorded, the operation does not succeed.

This page explains what that means in practice, what gets recorded, and why it’s a guarantee rather than a feature you have to enable.

Provenance by construction

Most systems treat audit trails as something bolted on: a log line, an event emitted after the fact, a table someone hopefully writes to. Those drift — code paths get added that forget to log, and the trail has holes.

Geopera inverts this. The operation pipeline has a fixed shape, and for any operation that isn’t a pure read it runs:

… → open provenance → execute → validate output → seal provenance → audit

The seal step enforces a contract: if an operation declares that it produces an artifact (an item, an order, a job…), it must have emitted that artifact’s lineage, or the operation fails closed with a provenance error — even if the underlying work “succeeded.” There is no flag to turn this off, and no privileged code path that skips it. A capability that produces data and forgets to record where it came from cannot ship.

The result: every produced artifact carries a complete record of how it came to exist, by construction.

What gets recorded

Each producing operation emits one or more artifacts, each linked by derived-from edges to the things it came from. The artifact kinds today:

Kind	Emitted by (examples)	Typically derived from
`order`	`orders.archive.place`, `orders.tasking.place`	the captures / AOIs it was placed for
`item`	`uploads.complete`, order delivery, processing output	the upload, order, or job that produced it
`asset`	asset ingestion	its parent item
`processing_job`	`processing.create`, `clip.create_from_item`	its input items/assets
`report`	`reports.generate`	the items/analytics it summarised
`share_link`	`share.link.create`	the item or collection it exports
`collection`, `project`	`collections.create`, `projects.create`	their parent scope

For example:

An archive order is recorded as an order artifact derived from each capture it ordered (relation: "ordered").
A delivered item is recorded as an item derived from its order (relation: "delivered_for").
An uploaded item is an item derived from its upload session (relation: "uploaded").
A clip output is an item derived from both the processing job (relation: "produced_by") and the source item it was clipped from.

Chained together, these edges form a walkable graph: a clipped item → the job that made it → the source item → the order that delivered the source → the captures that order bought. Lineage survives even if an upstream source is later archived.

The idempotent no-op

A producing operation that legitimately produces nothing on a given call — e.g. uploads.complete on an already-completed session, or an order placement that returned a cached result on an idempotent retry — marks itself an idempotent no-op. The seal contract recognises this and doesn’t demand a fresh emit. So idempotent retries stay safe and provenance stays honest: a record is written exactly when an artifact is actually created, and not otherwise.

Why it matters

Auditability — for any artifact you can answer “where did this come from?” with a record that was written atomically with the artifact, not reconstructed from logs.
Reproducibility — the inputs an output was derived from are captured, so a result can be traced back to exactly what produced it.
Trust across clients — because the guarantee lives in the kernel, it holds no matter who called the operation: the portal, an SDK, an AI agent, or a worker registering its job’s outputs all produce the same complete lineage.

Integrity of the record

The provenance store is written through a privileged, security-defined path: operations emit through the kernel, which writes the artifact and its edges atomically; application roles cannot write provenance rows directly. So the lineage graph reflects what the governed operations actually did — it can’t be forged by a client that bypasses the emit path, because there is no such path.

Reading lineage

Walk the graph over the API with provenance.get (scope provenance:read):

bash

curl -s -X POST https://api.geopera.com/v1/op/provenance.get \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "entity_type": "item", "entity_id": "it_3a9c...", "direction": "up", "max_depth": 20 }'

json

{
  "root": { "entity_type": "item", "entity_id": "it_3a9c..." },
  "direction": "up",
  "edges": [
    { "depth": 1, "src_type": "item", "src_id": "it_src...", "dst_type": "item", "dst_id": "it_3a9c...", "relation": "duplicated_from", "invocation_id": "..." }
  ],
  "nodes": [ { "entity_type": "item", "entity_id": "it_3a9c...", "depth": 0 }, { "entity_type": "item", "entity_id": "it_src...", "depth": 1 } ]
}

direction — up (ancestors: “how was this produced?”), down (descendants: “what came from this?”), or both. max_depth bounds the walk (1–50).
Supported root types: item, order, processing_job, collection, project.
Org-scoped: you can only read lineage for a root your organization owns — a cross-org or unknown root returns 404 (no existence leak), exactly like every other read.