Integrate an authenticated, freshness-aware production risk oracle

[knytcomics-ui]

Category

Advanced

Summary

Replace the deterministic local score generator with the production oracle adapter contract.

Current Behavior

src/adapter/oracleAdapter.ts computes scores with stubScoreFor(). Cache, retry, timeout, and circuit-breaker scaffolding exists, but no network-backed oracle is integrated.

Problem

The extension cannot currently provide real destination risk intelligence.

Why This Matters

The primary product value proposition depends on trustworthy, available, and explainable risk data.

Proposed Scope

Implement authenticated requests, response validation, freshness/provenance handling, network-aware inputs, bounded retries, cancellation, cache policy, and explicit Unknown failures.

Acceptance Criteria

• The adapter calls the production interface rather than the stub.
• Requests authenticate and validate responses.
• Freshness/provenance behavior is defined and enforced.
• Timeout, retry, cancellation, and circuit behavior are deterministic.
• Failures render Unknown rather than Low.
• Privacy documentation reflects transmitted data.
• Integration and failure-path tests are included.

Technical Considerations

The referenced grydlock-oracle-adapter repository is not present locally; request/response compatibility must be verified before implementation.

Testing Requirements

Mock success, malformed responses, authentication errors, timeouts, stale responses, retries, and circuit recovery.

Cross-Repository Impact

Extension ↔ grydlock-oracle-adapter request/response interface.

Out of Scope

Changing the scoring model or adding decision telemetry.

Complexity

Advanced — external integration with privacy, availability, and compatibility implications.

Impact

Critical — enables the actual product.

Suggested Labels

advanced, security, architecture, privacy

[Hollujay]

I would like to work on this issue because I will get it done @knytcomics-ui