---
id: capability.wiki.adapter-contract
name: Capability-Aware Shard Adapter Contract
summary: A versioned backend interface where each binding declares a verified capability profile (positions on capability spectra), so federation ops degrade by capability.
owner: shard-wiki
status: draft
domain: helix_forge
tags: [wiki, adapter, capability, contract, conformance, shard-wiki]

maturity:
  discovery:
    current: D5
    target: D6
    confidence: high
    rationale: >
      Fifteen capability spectra with an orthogonal core + implication rules, plus
      a normative contract spec (TSD Section A); derived from a ~23-system synthesis.
  availability:
    current: A2
    target: A5
    confidence: medium
    rationale: >
      AdapterContract + a read/write FolderAdapter + a conformance suite that
      verifies declared profile == observed behaviour exist as a source module.

external_evidence:
  completeness:
    level: C2
    name: Partial
    confidence: medium
    basis: scope_vs_intent_and_consumer_expectations
    satisfied_expectations:
      - versioned interface with declared, conformance-verified capability profiles
      - one concrete adapter (file-store) passes the conformance suite
    broken_expectations:
      - only one substrate implemented (git-IS-store, REST, CRDT adapters planned)
    out_of_scope_expectations:
      - hosting backends
  reliability:
    level: R1
    confidence: low
    basis: consumer_quality_signals
    known_reliability_risks:
      - single adapter implemented so far

discovery:
  intent: >
    Mediate heterogeneity at one narrow waist: a backend participates by implementing a
    versioned interface and declaring a verified position on each capability spectrum.
  includes:
    - capability profile as data (orthogonal-core spectra + implied positions)
    - operation verbs (read/write/diff/merge/notify/.../derive-projection/execute)
    - a conformance suite (profiles verified, not self-asserted)
  excludes:
    - assuming uniform backend capabilities
  use_cases:
    - "shard-wiki UseCaseCatalog UC-34..UC-43, UC-50, UC-57, UC-60..UC-69 (shard attachment & adapter binding)"

availability:
  current_level: A2
  target_level: A5
  current_artifacts:
    - "shard-wiki/src/shard_wiki/adapters/"
  consumption_modes:
    - source module

relations:
  depends_on:
    - capability.wiki.page-model
  supports:
    - capability.wiki.shard-orchestration

evidence:
  documentation:
    - "shard-wiki/spec/TechnicalSpecificationDocument.md (Section A)"
    - "shard-wiki/spec/CoreArchitectureBlueprint.md (Section 6)"
  tests:
    - "shard-wiki/tests/test_folder_adapter.py"
    - "shard-wiki/tests/test_conformance.py"

consumer_guidance:
  recommended_for:
    - exposing any page store as a capability-described, conformance-checked shard
  not_recommended_for:
    - backends that cannot honestly describe their capabilities
  known_limitations:
    - reference implementation covers the file-store substrate only so far
---

# Capability-Aware Shard Adapter Contract

The bottom narrow waist of shard-wiki: a versioned interface plus a **verified** capability
profile per binding. Core logic is written once against capabilities (not per-backend), and
the conformance suite rejects profiles whose declared abilities don't match observed behaviour.

## Assessment notes

### Discovery
Fifteen spectra reduced to an orthogonal core with implication rules (CoreArchitectureBlueprint
Section 6.5); normative in TSD Section A.

### Availability
`adapters/` ships the contract, a folder adapter, and `assert_conformant`.