ssot-pack-contracts 0.2.19.dev1

Shared governance-pack metadata, manifest, and packaged document contracts for SSOT.

ssot-pack-contracts

Shared metadata, manifest, and packaged-document contracts for installable SSOT governance packs.

ssot-pack-contracts is the shared Python contract layer for installable SSOT governance packs.

It gives external governance packs one common API for declaring pack identity, schema compatibility, trust metadata, document manifests, and packaged ADR/SPEC resources. It does not mutate .ssot/registry.json and does not depend on ssot-core or ssot-cli.

• GitHub: https://github.com/groupsum/ssot-registry/tree/main/pkgs/ssot-pack-contracts
• PyPI: https://pypi.org/project/ssot-pack-contracts/

What this package owns

• Governance-pack metadata loading and validation
• Governance-pack schema version access
• PyPI distribution name and version discovery through installed package metadata
• Pack document manifest loading for ADR and SPEC payloads
• Packaged document text and byte readers
• Document ID listing and manifest-entry lookup helpers
• Fail-closed validation errors for invalid pack metadata or manifest entries

When to use this package

Use ssot-pack-contracts when you are building an installable governance pack that ships SSOT ADRs, SPECs, or other governed pack documents as Python package resources.

Use another package when you want:

• ssot-contracts for canonical SSOT schemas, templates, and generated contract metadata
• ssot-core for registry loading, validation, synchronization, pack ingestion, and mutation APIs
• ssot-cli for operator commands such as pack inspection, preflight checks, and sync workflows
• ssot-registry for the umbrella runtime bundle

Governance packs using this contract

These governance packs are expected to expose the ssot-pack-contracts API surface from their package root:

• seo-aeo-aieo-governance-pack packages SEO, AEO, and AiEO governance ADR/SPEC content.
• digital-signature-governance-pack packages digital-signature governance ADR/SPEC content.
• cache-freshness-governance-pack packages cache freshness and cache governance ADR/SPEC content.

Each pack should depend on ssot-pack-contracts, include a packaged metadata.json, include declared document manifests, and bind the shared API at the package root.

Install

python -m pip install ssot-pack-contracts

For local development from this repository:

python -m pip install -e pkgs/ssot-pack-contracts

Pack authoring pattern

Governance packs should not reimplement the contract API. Their package root should bind and export the shared contract functions:

from ssot_pack_contracts import bind_pack_contract

globals().update(bind_pack_contract(__name__))

The binder resolves:

• __pypi_package_name__ from installed distribution metadata
• __version__ from importlib.metadata.version(...)
• __ssot_package_name__ from packaged governance metadata
• load_pack_metadata
• load_pack_schema_version
• load_pack_manifest
• load_document_manifest
• read_packaged_document_bytes
• read_packaged_document_text
• list_packaged_document_ids
• get_packaged_document_entry

Required metadata

Every governance pack must package a metadata.json resource at the import-package root. The metadata file is the source of truth for SSOT pack identity.

Required top-level fields:

{
  "schema_version": "1.0.0",
  "ssot_package_name": "example-governance-pack",
  "origin": {
    "id": "pack:example-governance-pack",
    "package_name": "example-governance-pack",
    "import_name": "example_governance_pack",
    "kind": "governance-pack"
  },
  "compatibility": {
    "python": ">=3.10,<3.15",
    "ssot_registry_schema": ">=0.4.0,<0.5.0",
    "ssot_pack_contract": ">=0.2.18,<0.3.0"
  },
  "trust": {
    "origin": "extension-pack",
    "trusted_by_default": false,
    "reservation_owner": "extension-pack:example-governance-pack"
  },
  "documents": {
    "adr": {
      "manifest_path": "adr/manifest.json"
    },
    "spec": {
      "manifest_path": "specs/manifest.json"
    }
  }
}

The package version is not authored in metadata.json. It is loaded from the installed PyPI distribution metadata, which is generated from the pack's pyproject.toml.

Public API

from ssot_pack_contracts import (
    bind_pack_contract,
    get_packaged_document_entry,
    list_packaged_document_ids,
    load_document_manifest,
    load_pack_manifest,
    load_pack_metadata,
    load_pack_schema_version,
    read_packaged_document_bytes,
    read_packaged_document_text,
)

Load pack identity and schema version:

from ssot_pack_contracts import load_pack_metadata, load_pack_schema_version

metadata = load_pack_metadata("seo_aeo_aieo_governance_pack")
schema_version = load_pack_schema_version("seo_aeo_aieo_governance_pack")

print(metadata["ssot_package_name"])
print(metadata["pypi_package_name"])
print(metadata["version"])
print(schema_version)

List and read packaged documents:

from ssot_pack_contracts import (
    get_packaged_document_entry,
    list_packaged_document_ids,
    read_packaged_document_text,
)

document_ids = list_packaged_document_ids("seo_aeo_aieo_governance_pack", "spec")
entry = get_packaged_document_entry("seo_aeo_aieo_governance_pack", document_ids[0])
body = read_packaged_document_text("seo_aeo_aieo_governance_pack", "spec", entry["filename"])

Contract rules

• Pack root APIs must be loaded from ssot-pack-contracts, not copied by hand.
• metadata.schema_version is required and must be available through load_pack_schema_version.
• metadata.ssot_package_name is required and must match metadata.origin.package_name.
• metadata.origin.import_name must match the installed import package.
• metadata.origin.kind must be governance-pack.
• metadata.trust.origin must be extension-pack.
• metadata.trust.reservation_owner must start with extension-pack:.
• metadata.compatibility.python, metadata.compatibility.ssot_registry_schema, and metadata.compatibility.ssot_pack_contract are required.
• Document manifest kinds must use normalized keys: adr and spec.
• Packaged document entries must include stable IDs, filenames, target paths, SHA-256 hashes, origin, reservation owner, compatibility metadata, status, and supersession fields.

Package relationships

• Package type: governance-pack contract package
• Depends on: standard library only, plus tomli on Python earlier than 3.11
• Used by: governance packs such as seo-aeo-aieo-governance-pack, digital-signature-governance-pack, and cache-freshness-governance-pack
• Consumed by: ssot-core pack ingestion and ssot-cli pack inspection, preflight, and sync workflows

If you are publishing an SSOT governance pack, use ssot-pack-contracts as the root API contract. If you are consuming packs, use ssot-cli or ssot-core to inspect, preflight, and synchronize pack content into a governed registry.