# Adapter Contracts

Adapters translate one canonical capability model into a harness-native projection. The compatibility rule is:

```text
canonical capability
  → verified native projection when available
  → semantics-preserving fallback otherwise
```

Adapter Knowledge records declared discovery paths and harness capabilities for a release. Directly contract-tested values are called out below; the remaining values are experimental profile knowledge, not proof of independent runtime behavior. These declarations are versioned knowledge, not permanent architecture contracts.

## Public projection contract

An adapter receives a `ProjectionInput` containing the exact toolkit version, canonical source hash, resolved policy, bundle map, existing artifact bytes, Repository Invariants, and scoped profile information. It returns `VirtualArtifact` values in memory. Projection itself performs zero filesystem writes.

Each artifact has a normalized repository-relative POSIX path, UTF-8 content, SHA-256, toolkit owner, and an operation intent (`create`, `replace`, or bounded Managed Region operation). The planner inspects current bytes and the applier is the only mutation boundary.

Generated artifacts carry ownership and self-integrity metadata:

```text
Generated by @agent-policy/agent-policy-toolkit.
Toolkit version: <exact release>
Adapter knowledge version: <tested adapter profile>
Canonical source hash: <hash of declared sources>
Artifact hash: <hash of this generated artifact with this line normalized>
Do not edit; change `.agent-policy/` and regenerate.
```

Generated skill ownership and self-hashes are line-ending tolerant for LF and CRLF, so a Windows checkout remains verifiable. The owner marker, artifact hash, and generated bytes are still checked; arbitrary edits remain drift.

## Codex `0.1.0-alpha.1` profile

Codex is experimental in this release. The declared Adapter Knowledge profile is `codex-2026-08-12`; evidence boundaries are listed per row:

| Capability | Declared profile value | Evidence boundary |
| --- | --- | --- |
| Instruction discovery | `AGENTS.md` | Directly contract-tested by Codex projection tests |
| Skill discovery | `.agents/skills/*/SKILL.md` | Directly contract-tested by Codex projection tests |
| Native roles | `false` | Declared experimental profile value; no role projection is emitted |
| Isolated work | `true` | Declared experimental profile value; not independently exercised here |
| Parallel work | `true` | Declared experimental profile value; not independently exercised here |
| Tool access | `harness-native` | Declared experimental profile value; not independently exercised here |
| Scoped instructions | `true` | Declared experimental profile value; projection text is contract-tested, harness selection is not |
| Support | `experimental` | Release boundary, not a semantic model-evaluation result |

The root projection inserts exactly one marker-delimited region:

```md
<!-- agent-policy:start owner=@agent-policy/agent-policy-toolkit -->
...
<!-- agent-policy:end -->
```

The region contains compact Core policy, selected Repository Invariants, and concise routing to generated skills. It does not inline domain rationales, full workflow or role bodies, evidence, or deferred capability text. Domain bundles are emitted as ordinary root-discoverable `.agents/skills/<bundle>/SKILL.md` files, never as symlinks. Their frontmatter descriptions include positive semantic hints, explicit exclusions, dependencies, and scoped path/workspace boundaries where configured.

The adapter preserves unmanaged bytes before and after an existing owned region. Missing `AGENTS.md` is created with only the owned region. Duplicate, nested, reversed, unmatched, foreign-owner, malformed, and truncated marker-like content is rejected as drift rather than repaired silently.

## Fallback behavior

The fallback contract is a semantic guarantee, not a promise that every native harness feature exists. When native discovery or role mechanisms are unavailable, an adapter must choose an ordinary generated projection or another tested fallback that keeps the capability's intended meaning discoverable. It must not silently drop the capability or claim native support.

Codex reports `nativeRoles: false`. Agent Role infrastructure and a role-specific Codex fallback are not implemented in the foundation slice, so this release emits no Agent Role projection and makes no role-support claim. A later slice must add and test that fallback before documenting it as available.

## Ownership and lifecycle constraints

Existing hand-written harness files are not classified as toolkit-owned. The adapter claims only its exact markers and generated headers. Update replaces only the owned Managed Region and toolkit-owned generated copies. Removal removes those projections while preserving `.agent-policy/` and unrelated text/files.

Generated-copy drift, manual Managed Region edits, foreign ownership, and invalid paths fail closed. Reconciliation can propose canonical source changes or a fresh regeneration plan, but the adapter never adopts or applies a changed artifact directly.

## Support boundary

Only Codex is implemented and contract-tested in `0.1.0-alpha.1`. Claude Code, OpenCode, Pi, Google Antigravity, native custom agents, and additional role/workflow projections are deferred. The foundation does not claim stable support for them by analogy with Codex.