Skip to content

Additional example read-only adapter, separate from the core, with a verifiable contract #4

Description

@klssxx

Context

THEKEY consumes external providers (e.g. NPSC) only through optional, read-only adapters. The core must not depend on any adapter to exist. src/thekey/adapters/npsc_adapter.py is the reference example.

Requisito o riesgo al que responde

  • Requisito: THEKEY_CONTRACT §4 (The verifier does not trust the implementer) and §5 — adapters are read-only and never execute the provider.
  • Riesgo cubierto: THREAT-T4 (untrusted input via adapter) — a second example adapter proves the contract is general, not NPSC-specific.

Impacto si no se resuelve

The "adapters are optional and read-only" claim is backed by a single example; a contributor has no second template to copy, increasing the chance of a core-coupled adapter.

Acceptance criteria

  • A second example adapter under src/thekey/adapters/ with a verifiable contract (input schema, output schema, read-only guarantee).
  • A test proves the core loads/runs with the adapter absent and with it present, and that the adapter cannot mutate the original repo.
  • Docs note adapters are optional and external.

Cómo se verifica

python -m pytest -q tests/test_adapters.py
# expected: all pass, including "adapter absent" and "read-only" cases
python -m thekey demo
# expected: RELEASE_ELIGIBLE, gates_passed: 4/4

Evidencia en event store

On merge record Closes #4 + the adapter contract test output in the PR body. The demo run must reach RELEASE_ELIGIBLE with evidence_mismatches: [] (no core behavior change recorded).

Docs afectados

  • README / README.en actualizado (adapters section)
  • CHANGELOG entrada añadida
  • DECISIONS.md si hay decisión de diseño

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesthelp wantedExtra attention is needed

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions