Extension Contracts

AGILAB is easier to maintain when every extension follows a small contract instead of adding page-specific or app-specific glue. This page is the public contract kit for new apps, page bundles, notebook bridges, proof evidence, connectors, and shared-core changes.

The machine-readable source is data/extension_contracts.toml. Maintainers can inspect it through the maintenance dashboard:

uv --preview-features extra-build-dependencies run python tools/maintenance_dashboard.py --json
./dev maintenance

Contract shape

Every extension type declares:

metadata: files, manifests, labels, or registration points that make the extension discoverable;
evidence: reports, run manifests, hashes, UI robot output, or verifier results that prove the extension boundary;
guardrails: tests or tools that fail before drift reaches release time;
maturity labels: the capability-map labels that separate shipped local paths, contract proofs, live checks, and roadmap boundaries.

Use Capability Map as the single reference for maturity-label meanings.

Extension types

Type	Maintenance rule	Primary guardrail	Typical evidence
`app`	Public apps must be installable, runnable, documented, and evidence-producing.	`tools/app_contract_matrix.py`	`run_manifest.json`, reducer summary, app artifacts.
`page_bundle`	Pages stay app-agnostic, dependency-isolated, and discoverable through provider/catalog metadata.	`tools/app_contract_matrix.py`	UI robot, static render, apps-pages docs row.
`notebook_bridge`	Notebook import/export must preserve stage order, runtime hints, role metadata, and artifact references.	Notebook preflight and round-trip reports.	Import preview, `lab_stages.toml`, supervisor notebook export.
`proof_evidence`	Evidence surfaces must have schemas, producer commands, verifier behavior, and explicit claim boundaries.	Evidence claims policy and release proof checks.	Plain JSON, `.agipack`, verifier report, promotion dossier.
`connector`	Connectors reference data systems by ID and credential reference, not by embedded secrets or hidden local paths.	Connector facility, resolution, and adapter reports.	Local proof, contract proof, emulator proof, or live probe result.
`shared_core`	Shared runtime or installer changes need explicit blast-radius analysis and focused regression evidence before merge.	`tools/impact_validate.py` and shared-core typing.	Impact report, focused tests, docs when public behavior changes.

Adoption rule

Before adding a new feature, choose its extension type and maturity label. If a feature does not fit any row, add or revise the contract first. This keeps AGILAB maintainable as the number of apps, page bundles, connectors, and proof surfaces grows.

Release rule

Do not promote an extension as public-ready until its metadata, evidence, docs, and guardrails are all present. For split packages, the package split and release plan remain the source of truth for what is published.