contract

README

contract/: Ecosystem Adapter Contract Test Suite

This package is the public validation gate for any Hydaelyn ecosystem adapter that implements a kernel interface. Spec anchor: docs/product-spec/v0.8.0/07-storage.md §"Contract test suite" + ADR-012.

Position D in one sentence

The framework owns the contract and the contract test suite. The framework ships no api.StoreProvider implementation. Applications implement the contract against their own data stack.

If your provider passes contract.RunStoreProviderContractTests, it is correct as far as Hydaelyn is concerned. The framework runs the same suite on every PR via a non-exported in-memory adapter at contract/internal/inmemfake/; see ADR-012 (revised, Position D).

Usage from an external adapter

package mystorage_test

import (
    "context"
    "testing"

    "github.com/Viking602/go-hydaelyn/api"
    "github.com/Viking602/go-hydaelyn/contract"
    "example.com/myorg/mystorage"
)

func TestMyProvider_ContractCompliance(t *testing.T) {
    contract.RunStoreProviderContractTests(t, func(t *testing.T) (api.StoreProvider, func()) {
        db := newTestDB(t) // your test setup
        provider := mystorage.New(db)
        cleanup := func() { _ = provider.Close(context.Background()) }
        return provider, cleanup
    })
}

What this package contains

RunStoreProviderContractTests is the package's only exported contract suite. It runs eight top-level groups with executable assertions:

Group	Coverage
CRUD	Required store reads, writes, and selectors
Transactions	Commit, rollback, read-own-writes, and isolation
LeaseCAS	Version checks, ownership, transfer, and concurrent acquisition
EventOrdering	Append order, run filtering, and monotonic sequence
ResumeAndOutbox	Pending resume tokens, pagination, queue state, and FIFO order
ReplayDeterminism	Stable full and partial replay
CapabilitySelfConsistency	Declared optional capabilities match runtime behavior
MultiAgentStores	Handoff, team-state, and agent-instance persistence

These are real tests, not placeholder stubs. t.Skip is used only for the optional list-pending scenarios when a provider reports that capability as unsupported. Required store behavior cannot be skipped. The framework verifies the suite against contract/internal/inmemfake on every PR.

Extending the suite

1. Add the smallest executable assertion to the relevant group. Create a new top-level group only for a distinct contract area.
2. Obtain a fresh provider through ProviderFactory and register cleanup with the test.
3. Gate a test with t.Skip only when the public capability contract declares the behavior optional.
4. Update 07-storage.md when the storage contract changes.
5. Run go test ./contract against the internal self-check adapter.

Documentation

Overview

Package contract provides public conformance tests for application-owned api.StoreProvider implementations.

Under Position D, Hydaelyn owns the storage contract verbs and their conformance tests. Applications own schema and implementation. The framework ships no reference StoreProvider implementation; contract/internal/inmemfake exists only to verify the suite itself. Application implementations should call RunStoreProviderContractTests from their own test packages.

See ADR-012, ADR-013, and the v0.8.0 storage contract.

Index

• func RunRecoveryContractTests(t *testing.T, factory RecoveryProviderFactory)
• func RunStoreProviderContractTests(t *testing.T, factory ProviderFactory)
• type ProviderFactory
• type RecoveryProviderFactory

Functions

func RunRecoveryContractTests

func RunRecoveryContractTests(t *testing.T, factory RecoveryProviderFactory)

RunRecoveryContractTests proves runtime-loss recovery through separate production Runner instances sharing one committed StoreProvider state.

func RunStoreProviderContractTests

func RunStoreProviderContractTests(t *testing.T, factory ProviderFactory)

RunStoreProviderContractTests is the public contract gate for any api.StoreProvider implementation. External adapter authors call this from their own _test.go to verify their provider satisfies the framework contract.

v0.8.0 scope: 42 named subtests across CRUD, transactions, lease CAS, event ordering, resume tokens + outbox, replay determinism, capability self-consistency, and the multi-agent stores (HandoffStore / TeamStateStore / AgentInstanceStore — spec 07 §"New store contracts"). See docs/product-spec/v0.8.0/07-storage.md §"Contract test suite" for the authoritative list. See ADR-012 for the Position D stance. Application-owned StoreProvider implementations should run this suite. The framework ships no reference StoreProvider implementations.

Tests gated on optional capabilities call t.Skip when the provider self-declares the feature as unsupported via api.CapabilityReporter, so the suite never fails a conformant provider that simply does not opt in.

Types

type ProviderFactory

type ProviderFactory func(t *testing.T) (provider api.StoreProvider, cleanup func())

ProviderFactory builds a fresh StoreProvider for one test. The returned cleanup func runs after the test (via t.Cleanup).

type RecoveryProviderFactory

type RecoveryProviderFactory func(t *testing.T) (
	open func() api.StoreProvider,
	cleanup func(),
)

RecoveryProviderFactory creates an isolated backing store for one recovery contract case. Every call to open must return a provider handle exposing the same committed state. cleanup releases the backing store after the case.