Skip to content

feat(observation): add stable observed-state fingerprints - #189

Merged
ElliotSun merged 6 commits into
mainfrom
12-observed-state-fingerprint
Sep 1, 2026
Merged

feat(observation): add stable observed-state fingerprints#189
ElliotSun merged 6 commits into
mainfrom
12-observed-state-fingerprint

Conversation

@ElliotSun

Copy link
Copy Markdown
Collaborator

Summary

Add a platform-neutral, versioned semantic fingerprint for ObservedPlatformState so repeated observations can distinguish state changes from observation-envelope changes.

Semantics

The fingerprint identifies what platform state was observed, not where/when the observation happened.

Included in obs-v1:

  • state platform;
  • canonical asset identity;
  • asset type;
  • canonical property identity;
  • physical type;
  • nullability.

Excluded:

  • source_identifier;
  • captured_at;
  • an existing fingerprint value;
  • rich evidence not yet present in the minimal observation model.

Format:

obs-v1:sha256:<hex-digest>

Canonicalization

  • canonical JSON with sorted keys;
  • assets sorted independently of adapter/upstream ordering;
  • properties sorted independently of adapter/upstream ordering;
  • identity values use existing canonical_key semantics;
  • provider-specific physical-type interpretation remains in provider adapters, not the fingerprint layer.

Changes

  • add semapact.observation.fingerprint with canonical payload, hash, and immutable-copy helpers;
  • populate the fingerprint on Databricks observations after mapping to the platform-neutral model;
  • export the fingerprint API from semapact.observation;
  • add a fixed golden v1 digest and determinism/change-sensitivity regression tests;
  • update Databricks observation tests to require a populated stable fingerprint.

Boundary

Databricks TableInfo
        ↓
platform-neutral mapping
        ↓
ObservedPlatformState
        ↓
platform-neutral fingerprint
        ↓
fingerprinted ObservedPlatformState

No reconciliation, drift classification, contract import, governance, deployment, rich evidence, or lineage behavior is added here.

@ElliotSun
ElliotSun merged commit 440b00d into main Sep 1, 2026
9 checks passed
@ElliotSun
ElliotSun deleted the 12-observed-state-fingerprint branch September 1, 2026 10:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant