Specs¶

The spec format itself is described in the section reference. These are the objects that load and hold it.

load_spec ¶

load_spec(
    path: str | Path,
    *,
    env: str | None = None,
    profile_dirs: Sequence[Path] = (),
    resolvers: Sequence[ProfileResolver] | None = None,
    catalog: PluginCatalog | None = None,
) -> EffectiveSpec

Load harness.yaml with its profiles and environment overlay.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	The app spec, usually `harness.yaml`.	required
`env`	`str \| None`	Overlay to apply (`harness.<env>.yaml`); defaults to `$HARNESSWEAVER_ENV`. A missing overlay file is not an error; `spec explain` lists the layers used.	`None`
`profile_dirs`	`Sequence[Path]`	Extra directories to search for `org://` profiles.	`()`
`resolvers`	`Sequence[ProfileResolver] \| None`	Replace the default profile resolvers entirely.	`None`
`catalog`	`PluginCatalog \| None`	Where plugin profiles (`profile://<namespace>.<name>`) are found; defaults to the installed plugins.	`None`

Raises:

Type	Description
`SpecError`	See `spec_from_documents`.

EffectiveSpec `dataclass` ¶

EffectiveSpec(
    spec: HarnessSpec,
    data: Mapping[str, Any],
    provenance: Mapping[str, Provenance],
    locks: tuple[Lock, ...],
    bounds: tuple[Bound, ...],
    layers: tuple[Provenance, ...],
    level: LevelReport,
    path: Path | None = None,
)

An app's validated spec, with the layers, provenance, locks and bounds behind it.

origin ¶

origin(path: str) -> Provenance | None

The layer that set path (for example budgets.per_run.max_usd).

explain ¶

explain() -> list[ExplainRow]

Every effective value with its layer, lock and bounds (spec explain).

run_budget ¶

run_budget(
    task: str, overrides: Mapping[str, object] | None = None
) -> Budget

The budget for one run of task: per-run limits, tightened by the task's own.

overrides may only lower fields the task lists as overridable (R10).

Raises:

Type	Description
`SpecError`	If the task doesn't exist.
`BoundViolation`	If an override isn't allowed, raises a limit, or breaks a bound.

HarnessSpec ¶

The effective spec of one app, after every layer is merged (DESIGNS No. 11).

Level ¶

Bases: StrEnum

Adoption levels (DESIGNS No. 11).