bijux-proteomics-foundation 0.3.8

Schema governance and canonical serialization primitives for reproducible proteomics documents and cross-package compatibility

bijux-proteomics-foundation

bijux-proteomics-foundation is the shared contract kernel for the package family, including canonical JSON behavior, deterministic hashing, document fingerprints, and compatibility contracts for persisted scientific records.

Within the suite, foundation owns shared contracts, identifiers, and deterministic serialization.

Use this package when you need versioned document governance, migration-safe serialization, and cross-package consistency for reproducible proteomics data.

At a glance

• Use foundation when the problem is shared document identity, canonical JSON, compatibility checks, or durable hashing across package boundaries.
• Start with the stable root imports for shared contracts, then open the foundation handbook when you need the full owner surface.
• Route scientific meaning to core, execution to runtime, recommendation posture to intelligence, scientific memory to knowledge, and assay follow-up to lab.

Why teams pick this kernel

• one canonical document-contract baseline across every proteomics package
• stable fingerprints for cache keys, lineage, and provenance checks
• compatibility helpers for migration-safe long-lived scientific records
• small shared primitives that keep downstream packages from rebuilding the same durable contract logic

Typical use cases

• define document metadata with explicit version and compatibility policy
• serialize domain models into canonical JSON for reproducible comparisons
• validate migration paths before accepting persisted record upgrades
• centralize shared contract behavior so other packages stay focused on domain logic

0.3.8 Release Highlights

• The shared kernel now covers canonical document metadata, JSON rendering, stable hashing, identifier kinds, refusal and result envelopes, and schema compatibility checks in one bounded package.
• Foundation also ships the shared optional-dependency guards, alias helpers, generated-file markers, and reusable test-policy primitives that the release gates now depend on.
• The public root stays intentionally small while durable owner families make long-term boundaries explicit for contributors and downstream packages.

Installation

pip install bijux-proteomics-foundation

Test install:

pip install -e '.[test]'

Quick start

from bijux_proteomics_foundation import DocumentSchema, hash_payload, to_canonical_json

Public APIs

The stable root API is intentionally small:

• DocumentSchema for durable metadata on persisted artifacts
• to_canonical_json(...) for deterministic serialization
• hash_payload(...), hash_text(...), and hash_model(...) for reproducible fingerprints
• JsonModel plus typed identifiers such as ProgramId, TargetId, and ClaimId

Minimal executable example:

from bijux_proteomics_foundation import DocumentSchema, hash_payload, to_canonical_json

schema = DocumentSchema(
    created_by="bijux-proteomics-foundation",
    document_kind="readme_example",
    package_name="bijux-proteomics-foundation",
)
payload = {
    "document_kind": schema.document_kind,
    "schema_version": schema.schema_version,
}
rendered = to_canonical_json(payload)
fingerprint = hash_payload(payload)

assert '"readme_example"' in rendered
assert len(fingerprint) == 64

Package identity

• Distribution name: bijux-proteomics-foundation
• Import root: bijux_proteomics_foundation
• Stable entrypoints: bijux_proteomics_foundation, compatibility, identity, outcomes, serialization, and support

Package boundaries

This package owns shared document metadata, canonical serialization, and migration compatibility helpers as a shared kernel rather than a user-facing workflow package.

It does not own product decision logic, lab logic, or runtime orchestration. The exact allowed primitive surface is audited in support/charter.py.

What this package must not do

• it must not define workflow orchestration, provider binding, or operator entrypoints
• it must not own scientific evidence semantics, recommendation policy, or lab planning rules
• it must not become a generic dumping ground for single-package helpers that do not belong in the shared kernel

Contract checkpoints

• equivalent models must serialize to identical canonical JSON and fingerprints
• compatibility evaluation must report explicit status and reason text
• migrations must preserve semantic meaning while advancing declared versions
• downstream packages may depend on these primitives, but should not move domain rules into this layer

Contract examples

These examples stay at the shared-kernel layer. Workflow-owned, CLI-owned, and runtime-owned examples belong in the package that owns that behavior.

Document metadata:

from bijux_proteomics_foundation import DocumentSchema

schema = DocumentSchema(
    created_by="bijux-proteomics-foundation",
    document_kind="contract_bundle",
    package_name="bijux-proteomics-foundation",
    package_version="0.3.8",
)

Identifiers:

from bijux_proteomics_foundation.identity.identifiers import (
    IdentifierKind,
    build_identifier,
)

run_id = build_identifier(IdentifierKind.RUN, "Orbitrap Batch 7")

Canonical serialization and hashing:

from bijux_proteomics_foundation import hash_payload, to_canonical_json

payload = {"a": 1, "b": 2}
fingerprint = hash_payload(payload)
rendered = to_canonical_json(payload)

Refusals:

from bijux_proteomics_foundation.outcomes.refusals import OperationRefusal, RefusalKind
from bijux_proteomics_foundation.support.states import SupportState

refusal = OperationRefusal(
    operation="artifact_validation",
    kind=RefusalKind.UNSUPPORTED,
    code="unsupported_construct",
    reason="the payload cannot be normalized without changing shared meaning",
    support_state=SupportState.REFUSED,
)

Error envelopes:

from bijux_proteomics_foundation.outcomes.failures import (
    ErrorCategory,
    ErrorEnvelope,
)

envelope = ErrorEnvelope(
    category=ErrorCategory.RUNTIME,
    code="contract_rejection",
    message="canonical document validation rejected the payload",
)

Operation results:

from bijux_proteomics_foundation.outcomes.results import OperationResult

result = OperationResult.success(
    operation="contract_validation",
    summary="shared contract validation completed successfully",
    output_fingerprint="a" * 64,
)

Choose this package when

• you need reusable schema, serialization, identifier, or migration primitives
• the same document contract must stay consistent across multiple package layers
• the change is low-volatility shared infrastructure rather than package-specific domain behavior

Route elsewhere when

• the change defines lifecycle, ranking, evidence, lab, or runtime semantics
• the helper would only serve one higher-layer package instead of the shared family
• the work mainly reshapes transport or orchestration payloads instead of shared document primitives

Verification route

• check tests for schema, serialization, and migration proof before treating a foundation change as safe
• review docs/BOUNDARIES.md, docs/CONTRACTS.md, and docs/ARCHITECTURE.md when ownership or stability claims are part of the change
• review support/charter.py when the question is whether a new primitive belongs in foundation at all
• use README.md, CHANGELOG.md, and package docs/*.md when the change affects package publication, metadata, or release-readiness expectations

Review questions

• does the change preserve reusable schema, serialization, identifier, or migration behavior rather than higher-layer policy or execution logic
• would two or more downstream packages otherwise duplicate or drift on the same document primitive if this stayed outside foundation
• can the change be justified without claiming lifecycle, evidence, ranking, lab, or runtime orchestration ownership

Escalation route

• route the change upward when the primitive only serves one domain package instead of the shared family
• stop and review docs/BOUNDARIES.md and docs/ARCHITECTURE.md when the proposal starts carrying lifecycle, evidence, ranking, lab, or runtime terms
• escalate to the owning higher-layer package before release when downstream consumers would need package-specific exceptions to adopt the change

Consumer impact signals

• expect broad downstream review when schema, serialization, identifier, or migration primitives change because every package may consume them
• treat changes that alter canonical JSON, fingerprints, or compatibility status as high-impact even when APIs stay stable
• expect a lower release burden when the change only tightens internal implementation without changing shared document behavior

Explicit non-goals

• this package does not define lifecycle, evidence, ranking, lab, or runtime semantics
• this package does not coordinate workflow-local adapters or operator-facing orchestration
• this package does not carry compatibility-only shims that belong in a higher canonical layer or in the compat package

Source guide

• src/bijux_proteomics_foundation/serialization/document_schema.py for document metadata and audit lineage
• src/bijux_proteomics_foundation/serialization/scientific_values.py for nullability, duration, timestamp, and coordinate wrappers
• src/bijux_proteomics_foundation/compatibility/schema_assessments.py for compatibility and schema-evolution assessments
• src/bijux_proteomics_foundation/serialization/canonical_json.py for canonical serialization
• src/bijux_proteomics_foundation/serialization/stable_hashes.py for deterministic hashing policies
• src/bijux_proteomics_foundation/serialization/json_contracts.py for reusable JSON-backed contract helpers
• src/bijux_proteomics_foundation/identity/identifiers.py for shared identifier contracts
• src/bijux_proteomics_foundation/support/provenance.py for provenance pointers and adjacent support-state contracts
• src/bijux_proteomics_foundation/outcomes/failures.py for structured machine-readable failure contracts
• src/bijux_proteomics_foundation/outcomes/results.py for shared refusal and operation-result contracts
• src/bijux_proteomics_foundation/compatibility/schema_migrations.py for migration behavior
• tests for executable behavior expectations

Documentation

• Product overview
• Workflow families
• Product architecture
• Cross-package ownership
• Package guide
• Ownership boundary
• Architecture overview
• Interface contracts
• Release and versioning