DATA BASTION

§01 · AUDIT · PROVENANCE · OSDU NATIVE

Every record knows where it came from.

Provenance is not a feature we bolted on. It is the OSDU record shape itself — acl, legal tag, kind, version — written at materialization time, queryable forever.

§02 · PROVENANCE IS THE RECORD SHAPE

Four fields, written by the materializer, never optional.

Every record in the OSDU partition carries four invariants the schema will not let you skip: an acl (who can read and write), a legal block with legaltags (what jurisdiction and license the data was acquired under), a kind (the canonical schema id, e.g. osdu:wks:master-data--Well:1.0.0), and a version (a monotonic OSDU integer assigned on every write).

Concrete: the Tecpetrol materializer writes legaltags: ["osdu-tecpetrol-data"] on every record it creates. The legal tag itself is a first-class OSDU object — it has its own owner, its own expiry, its own country-of-origin. Strip the tag, you strip the record's right to exist. There is no path to “data without lineage” in this stack.

§03 · QUERYABLE HISTORY

Every edit returns a new version. The prior version stays GET-able forever.

Two endpoints carry the audit surface:

  • GET /api/wells/{id}/versions returns the full ordered list of version ids for a given record — newest first, with the materializer or human author stamped on each entry.
  • GET /api/audit?record={id}&from=…&to=… returns the edit log: who wrote, when, from which source (MQTT topic, batch ingest, manual patch), and a diff pointer to the prior version.

A PATCH on any record does not overwrite. It writes a new version, increments the OSDU version integer, and leaves the prior version retrievable by GET /api/storage/v2/records/{id}/versions/{version}. There is no DELETE path that drops history — soft-delete only, with the tombstone itself versioned.

Audit history panel: ordered version list with timestamp, action, version id, and author for a single OSDU record.
audit-history.png · 1440x900 · 2026-06-18
  1. 2026-06-15 · 10:42 CREATE v1 materializer wrote canonical record from MQTT batch ingest-bot
  2. 2026-06-15 · 14:08 UPDATE v2 patched FacilityName after operator review pedro@picolli
  3. 2026-06-17 · 09:31 UPDATE v3 corrected SpatialLocation after re-survey val@picolli

§04 · THE REGULATOR SCENARIO

60 seconds, end-to-end, in OSDU.

An investigator emails: show me the data behind well X's Q3 2024 production figure. Here is the walkthrough.

  1. Pull the well.

    GET /api/wells/X returns the canonical master-data--Well record. The legaltags field says osdu-tecpetrol-data. The kind says Aramco Standard 1.0.0. Provenance is on the record itself.

  2. Pull the volumes.

    GET /api/production?well=X&from=2024-07-01&to=2024-09-30 returns 90 ProductionVolumes records. Each carries the same legal tag and a createTime stamped by the materializer.

  3. Pull the materializer trail.

    GET /api/audit?record={any volume id} returns the materializer run id, the input window, and the source: MQTT topic tecpetrol/<wellId>/production, message ids, broker timestamps.

  4. Hand it over.

    Three JSON payloads. One legal tag. No spreadsheet, no screenshot, no apology.

§05 · CLOSE

Audit-grade is the default posture, not a premium tier.

Every pilot ships with the audit endpoints live and the legal-tag scaffold pre-populated for your jurisdiction. Day one, your data is provenance-complete.

Scope a 90-day pilot Talk to us