Artifact identity and evidence bundles#

A useful research record must preserve more than a friendly filename. LunarTrace’s canonical bundles bind scientific objects to exact dependencies and distinguish those identities from source locators and claims.

Locator versus identity#

A PDS product identifier names a scientific source object. A URL locates a resource. A SHA-256 digest identifies a particular byte sequence. Those are related, but not interchangeable.

A URL may later serve different bytes. A matching hash establishes byte agreement with the recorded expectation, not independent source authenticity. A scientific claim requires additional context and evidence.

Canonical Python bundle#

The existing bundle exporter writes content-addressed objects and semantic representations such as:

  • event/reference;

  • protocol;

  • archive snapshot and query scope where available;

  • currentness;

  • observations, pairs, and screening for compiled Studies;

  • historical aggregates and reference products for historical Studies;

  • evidence and provenance;

  • Study schema;

  • Study artifact;

  • dependency payloads.

The friendly entry points include study.json, manifest.json, and manifest.sha256. The manifest binds expected dependencies rather than treating loose files as implicitly complete.

Export validates the Study object again instead of trusting construction bypasses. Referenced dependency bytes must exist and agree with their expected hashes. A different existing manifest is not silently overwritten.

Why historical and compiled bundles differ#

A compiled Study can contain real normalized observation rows, pair rows, and screening results. A historical aggregate without original rows cannot create those payloads retrospectively.

The manifest records row availability so tools can expose only the operations supported by the retained evidence. No exact-table or replay capability should be inferred from the presence of aggregate counts.

The Lab export is different#

An EXPLORATORY_LAB_EXPORT is a transport envelope for a browser investigation. It can retain actual raw metadata-response bytes and the user’s exploratory choices, but it is not automatically a canonical bundle.

Its normalized projection uses browser-oriented JSON and a separate digest. Do not equate that digest with Python’s canonical scientific serialization. The initial Python bridge audits supplied response bytes and creates a new explicit acquisition for canonical work rather than pretending the two formats are identical.

Failure and partial custody#

A metadata hash mismatch is an integrity failure. It should remain a failure through a subsequent unsuccessful retry, not silently reset into permission to display or reuse the object.

An interrupted acquisition or export is not a complete result merely because some files were written. Retain the failure receipt, identify which dependencies remain available, and verify the final manifest before relying on the bundle.

Sharing and archival claims#

A shared draft URL is an intent-sharing mechanism. A public Worker distributes an application. A local folder retains files. None alone is permanent scholarly archival custody.

Before citing a result, retain the exact source/software revision, query and protocol, relevant raw dependencies, artifact identities, and the interpretation’s evidence ceiling. Publication and archival policies remain separate owner decisions.