# Schema Module Split Contract

## Scope

This contract defines the package ownership boundaries needed before splitting
`src/anima/core/schemas/models.py`.

Non-goals:

- no runtime behavior changes
- no persona format redesign
- no config package split beyond explicit ownership markers in this document

## Ownership Matrix

### `src/anima/core/contracts/`

Owns external contract payloads and small cross-cutting value types that are
consumed by multiple runtime paths but do not represent mutable execution state.

Moves here now:

- `JobSpec`
- `CapabilityToken`
- `Meta`

Stays out:

- `PersonaSpec` because repository target architecture assigns persona rules to a
  future `core/personas/` package, which is not introduced in this wave
- `AgentStateData` because mutable runtime state belongs to execution
- `ContextBundle`, `RawTailEntry`, `SummaryRef`, and `CompactionConfig` because
  pruning and compaction belong to conversation

### `src/anima/core/execution/`

Owns immutable execution-contract truth plus mutable persisted execution state.

Moves here now:

- `AgentStateData`
- `AgentResult`
- `TokenUsage`
- `ToolCallCount`
- `LogEntry`
- existing `ExecutionIntent*`, `Resolved*`, and execution consumer views remain
  here

Rationale:

- proposal guidance places execution intent, resolved contract, lifecycle rules,
  and budget policy in `core/execution/`
- `AgentStateData` already documents that it owns mutable runtime state only and
  must not absorb resolved execution truth

### `src/anima/core/conversation/`

Owns anima-native conversation, bundle, prune, and compaction data contracts.

Moves here now:

- `CompactionConfig`
- `RawTailEntry`
- `SummaryRef`
- `ContextBundle`

Conversation-owned compaction boundary types:

- `ConversationMessageView`: canonical anima message shape for prune/compaction
- `ConversationSummaryView`: canonical summary reference shape
- `ContextBundleView`: shared-context handoff contract
- `CompactionSessionView`: session-level read shape for prune/compaction inputs

Rationale:

- repository target architecture assigns anima-owned conversation/session event
  modeling and pruning/compaction work to `core/conversation/`
- current `core/compaction.py` still uses generic mapping aliases; future work
  should target these anima-owned conversation interfaces instead of adapter
  message types

### `src/anima/core/schemas/`

Becomes a compatibility and residual-schema package.

Remains owned here for this wave:

- `PersonaSpec`
- `CanSpawn`
- `GlobalDefaultsConfig`
- `ToolPresetConfig`
- `ToolOutputProviderProfile`
- `ToolOutputModelProfile`
- `ToolOutputToolDefault`
- `ToolOutputGovernanceConfig`
- `AnimaGlobalConfig`
- enums and errors

Compatibility role:

- `anima.core.schemas` remains the temporary public barrel for moved symbols
- `anima.core.schemas.models` remains a compatibility source during migration,
  but new imports should prefer the owning package
- no new execution or conversation types should be introduced directly into
  `core/schemas/models.py`

## Import And Barrel Rules

1. New code imports from the owning package, not `anima.core.schemas`.
2. `anima.core.schemas` re-exports moved symbols for compatibility only.
3. `anima.core.schemas.models` is transitional and should shrink over time.
4. `PersonaSpec` stays on the compatibility side until a dedicated
   `core/personas/` package exists.

## Stub Package Shape

### `src/anima/core/contracts/specs.py`

- transitional aliases for `JobSpec`, `CapabilityToken`, and `Meta`
- protocol stubs for narrow contract consumers

### `src/anima/core/execution/state.py`

- transitional aliases for mutable-state and execution-result models
- protocol stubs for consumers that only need persisted-state slices

### `src/anima/core/conversation/contracts.py`

- transitional aliases for bundle and compaction-related schema models
- protocol stubs for anima-owned message and session views

## Open Questions

- whether `GlobalDefaultsConfig` and tool-output config types should later move
  under a dedicated config package instead of remaining in `core/schemas/`
- whether `PersonaSpec` should move directly to `core/personas/` or first pass
  through `core/contracts/` as an intermediate migration step
