# Contract Design — Questions

> Fill in each `[Answer]:` tag. Options A-E plus X (Other). The file is the
> authoritative record of your contract decisions.

## Q1: Contract representation

How should the inter-unit contracts (Generator ↔ AiDraft, Generator ↔ Funnies, and the DraftBundle handoff) be specified?

A) Shared-schema contracts in Python (data classes / pydantic-style models) that live with the producer unit and are referenced by consumers — ideal for a local library-backed tool (recommended)
B) A standalone JSON-schema file per contract, imported by all units
C) Formal OpenAPI/AsyncAPI specs — heavier than a local tool needs
X) Other (please specify)

[Answer]: A

## Q2: Integration mechanism

How do the units call each other at the library boundary?

A) Direct module/function calls (the `newspaper` CLI imports the ai-draft and funnies libraries and calls their entry functions in-process) (recommended)
B) Each unit is a separate process, communicating via JSON over a pipe/CLI
C) A message/event bus between units
X) Other (please specify)

[Answer]: A

## Q3: Contract ownership

Who owns each contract spec?

A) Each producer unit owns the contract for data it emits — AiDraft owns the DraftBundle shape, Funnies owns the puzzle/cartoon output shape, Generator owns content/config input shapes (recommended)
B) A shared "contracts" home owned jointly
C) The CLI (Generator) owns all contracts centrally
X) Other (please specify)

[Answer]: A

## Q4: Error / timeout / fallback behaviour

How should the boundaries handle failure (e.g. Ollama unavailable, Funnies finds no cartoon, missing content)?

A) Fail gracefully: each unit returns a clear error/fallback (Ollama down → skip drafting with a message; no cartoon → tasteful placeholder; missing content → guided empty state), never a crash or blank page (recommended)
B) Hard-fail loudly with a clear message and non-zero exit
C) Best-effort only — ignore failures silently
X) Other (please specify)

[Answer]: A

## Q5: Versioning policy

How should internal contract changes be handled (this is a one-shot local tool)?

A) No formal versioning — additive, backward-compatible changes only within/after a build; breaking changes are re-generated in one go (recommended)
B) Semantic versioning of the library API, since content/consumers could persist between runs
C) Locked/immutable — contracts cannot change after review
X) Other (please specify)

[Answer]: A

## Consolidated Summary Confirmation

> Summary of your five contract answers before the contract summary is generated:
>
> - Contract representation: **shared-schema contracts in Python** (data classes / pydantic-style), referenced by consumers (Q1=A)
> - Integration mechanism: **in-process module/function calls** — the `newspaper` CLI imports the ai-draft and funnies libraries (Q2=A)
> - Contract ownership: **each producer owns its contract** — AiDraft owns the DraftBundle shape, Funnies the puzzle/cartoon output, Generator the content/config input shapes (Q3=A)
> - Error/fallback: **fail gracefully** — Ollama down → skip draft with a message, no cartoon → tasteful placeholder, missing content → guided empty state; never crash or blank (Q4=A)
> - Versioning: **no formal versioning** — additive backward-compatible changes; breaking changes regenerated in one go (Q5=A)
>
> Human pre-approved this summary (answers recorded via the file, self-guided mode).

Does this all look correct before I generate the contract summary?

- Looks correct
- Request changes

[Answer]: Looks correct