Skip to content

interface.md

Latest commit

 

History

History
84 lines (67 loc) · 4.26 KB

interface.md

File metadata and controls

84 lines (67 loc) · 4.26 KB
Raw

Shared object-storage contracts

Documentation / Public package reference

Audience: application composition and object-storage Adapter authors. Status: implemented SDK-independent contracts, currently consumed by the MinIO Adapter. Package: github.com/frost-leo/fathomry/adapters/objectstore/v1.

Responsibility

This is a real shared contract boundary, not an empty grouping package or a universal storage client. It imports public adapters/v1, never Internal, a concrete Adapter, an SDK or Framework. Importing it creates no source, worker, connection, registry or shutdown authority.

The owner requested this boundary during #104 implementation. It follows the existing database contract separation. Future Adapters may share these already-defined observations without adopting MinIO's addressing, grants, multipart protocol or client implementation.

Budgets and evidence

  • Budget declares root-family work and per-result evidence bytes. Providers derive effective envelopes from their actual implementation. These are not RSS measurements, distributed quotas or a promise about arbitrary native error graphs.
  • Policy combines Budget with explicit Runtime/Evidence options, including source ownership, sessions, incremental children and queued operations. ForGenerations(1..16) scales equivalent source/root/queue/evidence envelopes for overlap without altering per-root budgets or an existing runtime. It checks arithmetic limits, not provider compatibility.
  • Info identifies actual source preparation and copied provenance. Clone isolates both the outer provenance slice and nested field slices. Revision is opaque; configuration version, SDK version and public resource generation remain different axes.
  • Attribution freezes public correlation and the generation actually borrowed. Zero Source covers direct use and failed acquisition, not proof of absence.
  • Attempts counts observed dispatches. Inexact zero does not prove none occurred.
  • Effect distinguishes NotSubmitted, Unknown and Acknowledged for a provider-defined action. Acknowledgement does not prove prior existence, persistence, rollback, idempotency or business success. A later cleanup ACK must not overwrite an earlier uncertain action.

Info and Attribution are potentially sensitive process-local observations. Ordinary formatting is restricted and JSON serialization/reconstruction is refused. Explicit fields and detached copies remain caller-owned data. Budget/Policy are composition data, not runtime handles.

Concrete boundary and verification

MinIO owns its Settings, requests, immutable results, delegation, retained multipart/cursor handles and provider error definitions. Shared contracts do not expose an Internal bridge or unify future SDK methods.

Metadata tests, policy tests and integration tests check copying, diagnostics, overlap arithmetic and the actual dependency graph. The independent consumer uses both shared contracts and a selected concrete provider.

Package organization

The Adapter tree map defines this package's role and file responsibilities; shared mechanisms, capability vocabulary, preparation and concrete providers do not acquire identical APIs by convention.