# ADR 0002 — Distribute as an installable Python package bundling schemas and template

- Status: Accepted
- Date: 2026-07-05

## Context

Per ADR 0001, catalog repositories (e.g. `penumbra-scenarios`) and others must
consume the scenario-pack definition and tooling cleanly. The tools were written
for a monorepo layout: they resolve the schemas, the `_template`, the `_oracle`
model, and the contract version relative to their own location on disk
(`scenarios/…` under the repository root). That only works when the tools run
from inside a checkout that also contains the schemas and packs — it is not
consumable by an external project.

## Decision

Publish a single installable Python package, **`aces-scenario-packs`**, that
bundles both the tools and the canonical data:

- **Package layout** is `src/`-based: `src/aces_scenario_packs/` holds the tool
  modules; the schemas, the template pack, the shared oracle model, and the
  contract version are shipped as **package data** under the package.
- **Canonical resources** (schemas, template, oracle model, contract version)
  are loaded from the installed package via `importlib.resources`, never from the
  consumer's working tree.
- **The catalog under validation** (the consumer's `scenarios/<pack>/` tree) is
  supplied at runtime via an explicit root argument (default: the current
  directory). Canonical-resource resolution and catalog resolution are separate
  concerns.
- The package exposes **console entry points** (see ADR 0003) so a consumer runs
  `aces-pack-validate`, `aces-pack-release`, `aces-new-pack`, and
  `aces-pack-issue-skeleton` after `pip install`.

A single package (rather than split tool/schema packages) is chosen for consumer
simplicity: one dependency provides both the validators and the schemas they
enforce, guaranteeing they are version-matched.

## Consequences

- A consumer does `pip install aces-scenario-packs` and gets the tools plus the
  version-matched schemas and template; nothing is vendored.
- The tools are refactored so canonical-resource paths come from package data and
  the pack-catalog root is a parameter. Tests exercise the package-resource model
  against synthetic temporary catalogs.
- The schema/contract **content version** (the pack contract version and digest)
  is independent of the **package version** (see ADR 0003); the package declares
  which contract version it ships.