rif

README

Research Integrity Framework (RIF)

RIF currently provides repository-local research-integrity types, metrics/check helpers, JSON writers, and memory-only registry/lifecycle scaffolding. It does not presently guarantee research acceptance, candidate freeze, paper eligibility, promotion, or authorization.

The corrected code-backed boundary and hardened design are documented in ak-ops/docs/architecture/. Until that design is implemented, Engine-emitted research.lock, research_audit.json, and promotion_packet.json files are untrusted research diagnostics only.

Development

Required Go version: 1.25.6.

Standalone setup from a fresh clone:

git clone git@github.com:david22573/ak-rif.git
cd ak-rif
GOWORK=off go mod download
make verify

The first dependency download needs network access unless the module cache is already populated. After dependencies are available, make verify runs local formatting, vet, test, and build checks with GOWORK=off.

go.work is optional for local multi-repository development and is not required to build or test this repository. RIF is intended to own future acceptance and lifecycle policy. The current repository has no durable production acceptance consumer. Downstream repositories should use reviewed serialized contracts instead of importing RIF implementation packages solely to share structs.

Current code-backed scope

• Artifact helpers: Marshal research lock/audit/legacy packet-shaped Go values to JSON files. These bytes are not canonical or signed and are not durable acceptance records.
• Integrity helpers: Implement narrow sample-size, parameter-mining, timestamp-order, and regime-overlap checks.
• Metrics: Compute a set of float-based research metrics; only this package has focused metric tests.
• Memory-only scaffolding: Dataset/experiment/holdout registries and a candidate state helper exist in memory. Their state and decisions do not survive restart and are not authorization authority.

Not presently implemented

• strict completed-bundle parsing, duplicate-key/unknown-field rejection, canonical serialization, or material hash recomputation;
• independent Engine commit, candidate, dataset, manifest, PIT, coverage, count, or metric acceptance;
• durable evidence, rejection, conflict, replay, lifecycle revision, freeze, or current-state storage;
• trustworthy paper eligibility or any paper-run authorization;
• a signed promotion packet or deployment authorization.

What RIF Does Not Do

• Strategy Modifications: RIF does not change strategy calculations, trade counts, signal logic, or net PnL. It acts purely as a passive observer that audits and evaluates.
• Broker Connectivity: RIF does not touch execution logic or broker APIs.
• Feature Calculation: RIF does not compute indicators; it only consumes their metadata and resulting returns.

Legacy artifacts and their locations

The current Engine bridge may write files beside research reports:

1. <stem>.research.lock: caller-supplied/copied identity fields; not independently derived or accepted by RIF.
2. <stem>.research_audit.json: research assumptions and copied provenance; not a durable acceptance trail.
3. <stem>.promotion_packet.json: legacy authority-looking output controlled by an Engine boolean; not promotion, freeze, paper eligibility, deployment readiness, or authorization.

These files can be partial because they are direct multi-file writes without an atomic completion marker. They must not be consumed as authority.

research.lock can carry universe/lifecycle/snapshot/PIT fields when Engine copies them from a caller-selected dataset manifest. Current code does not recompute those hashes from authoritative bytes; field presence is not verification.

How to Verify a Lockfile

The lock comparison helper checks selected supplied strings. It does not recompute input hashes, and optional one-sided omissions can bypass material comparisons. It is suitable only as a narrow diagnostic:

err := f.VerifyLock(currentLock, storedLock)
if err != nil {
    // Compares selected supplied fields; this is not RIF acceptance.
}

Legacy Engine bridge behavior

The Engine bridge may set its local IntegrityPassed result false, downgrade its own research classification, and suppress its legacy packet when selected checks fail. This is Engine repository-local behavior, not an independent RIF lifecycle decision. Missing PIT evidence, coverage defects, copied hashes, restart/replay, and durable acceptance are not fully enforced.

Legacy warning vocabulary

The Engine bridge currently formats warning codes such as the following. Warning text or absence is not RIF acceptance:

• CODE: RIF_LOW_SAMPLE_SIZE - The number of observations is below the statistical minimum (default 30). Fix: Evaluate over a longer time horizon.
• CODE: RIF_LOOKAHEAD_BIAS - Time series data passed into RIF was out of order, indicating potential leakage. Fix: Fix event chronological sorting.
• CODE: RIF_PARAMETER_MINING_RISK - Degrees of freedom are too low (ratio of observations to parameters < 20). Fix: Reduce parameter count or expand dataset.
• CODE: RIF_HOLDOUT_OVEREXPOSED - Legacy vocabulary for holdout limits; current state is memory-only and does not freeze a candidate.
• CODE: RIF_UNIVERSE_MANIFEST_MISSING - Dataset provenance lacks complete universe manifest metadata. Fix: generate a universe manifest and pass it through the dataset manifest.
• CODE: RIF_UNIVERSE_NOT_POINT_IN_TIME - The universe policy is explicit, current-active, local-data-discovered, or unknown. Fix: use verified point-in-time listing and delisting metadata before strict promotion.
• CODE: RIF_SURVIVORSHIP_BIAS_RISK - Survivorship risk is not LOW. Fix: keep the result exploratory or provide proven historical listing/delisting evidence.
• CODE: RIF_LIFECYCLE_MANIFEST_MISSING - Dataset provenance lacks lifecycle hashes. Fix: generate an asset lifecycle manifest and pass it through universe/dataset manifests.
• CODE: RIF_LIFECYCLE_EVIDENCE_WEAK - Lifecycle evidence is local-data-only, current-active-only, user-provided-unverified, unknown, or otherwise insufficient. Fix: keep the result exploratory or provide verified historical lifecycle evidence.
• CODE: RIF_LIFECYCLE_LISTING_EVIDENCE_MISSING - Listing evidence is not verified for all relevant symbols.
• CODE: RIF_LIFECYCLE_DELISTING_EVIDENCE_MISSING - Delisting evidence is not verified for all relevant symbols.
• CODE: RIF_SURVIVORSHIP_NOT_SOLVED - The lifecycle evidence layer is present but does not prove survivorship-free research.
• CODE: RIF_EXCHANGE_SNAPSHOT_CURRENT_ONLY - Exchange metadata snapshots are current-only and do not prove historical availability.
• CODE: RIF_SNAPSHOT_ARCHIVE_DOES_NOT_COVER_RESEARCH_WINDOW - Snapshot coverage does not cover the requested research window.
• CODE: RIF_POINT_IN_TIME_EVIDENCE_PARTIAL - Snapshot evidence is partial for point-in-time claims.
• CODE: RIF_DELISTING_NOT_PROVEN - Snapshot evidence does not prove delisting status.

Structured warning JSON includes code, severity, reason, affected universe, affected dataset, affected symbol when applicable, blocks_promotion, and recommended_fix.

Documentation

Index

• type Candidate
• type CandidateState
• type Dataset
• type Experiment
• type Framework
  • func NewFramework(maxHoldoutExposures int) *Framework
  • func (f *Framework) CalculateMetrics(data metrics.TimeSeriesData, riskFreeRate, periodsPerYear float64) (metrics.MetricsReport, error)
  • func (f *Framework) GenerateAudit(packet audit.ResearchAudit, path string) error
  • func (f *Framework) GenerateLockfile(lock audit.ResearchLock, path string) error
  • func (f *Framework) GeneratePromotionPacket(packet lifecycle.PromotionPacket, path string) error
  • func (f *Framework) Integrity() IntegrityNamespace
  • func (f *Framework) VerifyLock(current, stored audit.ResearchLock) error
• type IntegrityNamespace
  • func (i IntegrityNamespace) CheckLookAheadBias(timestamps []int64) error
  • func (i IntegrityNamespace) CheckParameterMining(numObservations, numParameters int) error
  • func (i IntegrityNamespace) CheckRegimeLeakage(trainingRegimes, validationRegimes []integrity.Regime) error
  • func (i IntegrityNamespace) CheckSampleSize(numObservations, minRequired int) error

Types

type Candidate

type Candidate = core.Candidate

type CandidateState

type CandidateState = core.CandidateState

type Dataset

type Dataset = core.Dataset

Export core types for easy access

type Experiment

type Experiment = core.Experiment

type Framework

type Framework struct {
	Experiments       *registry.ExperimentRegistry
	Datasets          *registry.DatasetRegistry
	HoldoutProtection *registry.HoldoutProtection
	Lifecycle         *lifecycle.StateTransitionEngine
}

Framework acts as the unified, independent entry point for all Research Integrity features. It is designed to be consumed by ak-engine, ak-trader, and ak-scout.

func NewFramework

func NewFramework(maxHoldoutExposures int) *Framework

NewFramework initializes the RIF components.

func (*Framework) CalculateMetrics

func (f *Framework) CalculateMetrics(data metrics.TimeSeriesData, riskFreeRate, periodsPerYear float64) (metrics.MetricsReport, error)

CalculateMetrics uses the Institutional Metrics Engine to generate standardized performance data.

func (*Framework) GenerateAudit

func (f *Framework) GenerateAudit(packet audit.ResearchAudit, path string) error

GenerateAudit produces a research audit trail document.

func (*Framework) GenerateLockfile

func (f *Framework) GenerateLockfile(lock audit.ResearchLock, path string) error

GenerateLockfile produces a deterministic reproducibility lockfile.

func (*Framework) GeneratePromotionPacket

func (f *Framework) GeneratePromotionPacket(packet lifecycle.PromotionPacket, path string) error

GeneratePromotionPacket produces the evidence packet required for candidate promotion.

func (*Framework) Integrity

func (f *Framework) Integrity() IntegrityNamespace

Integrity provides a namespace for statistical integrity checks.

func (*Framework) VerifyLock

func (f *Framework) VerifyLock(current, stored audit.ResearchLock) error

VerifyLock checks if a current configuration matches the locked configuration.

type IntegrityNamespace

type IntegrityNamespace struct{}

func (IntegrityNamespace) CheckLookAheadBias

func (i IntegrityNamespace) CheckLookAheadBias(timestamps []int64) error

CheckLookAheadBias validates that timestamps do not imply looking into the future.

func (IntegrityNamespace) CheckParameterMining

func (i IntegrityNamespace) CheckParameterMining(numObservations, numParameters int) error

CheckParameterMining checks if the number of parameters is dangerously large.

func (IntegrityNamespace) CheckRegimeLeakage

func (i IntegrityNamespace) CheckRegimeLeakage(trainingRegimes, validationRegimes []integrity.Regime) error

CheckRegimeLeakage ensures that validation regimes do not overlap with training regimes.

func (IntegrityNamespace) CheckSampleSize

func (i IntegrityNamespace) CheckSampleSize(numObservations, minRequired int) error

CheckSampleSize ensures enough statistical power exists.