Metadata-Version: 2.4
Name: ssot-pack-contracts
Version: 0.2.19.dev1
Summary: Shared governance-pack metadata, manifest, and packaged document contracts for SSOT.
Author-email: Jacob Stewart <jacob@swarmauri.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/groupsum/ssot-registry/tree/main/pkgs/ssot-pack-contracts
Project-URL: Repository, https://github.com/groupsum/ssot-registry/tree/main/pkgs/ssot-pack-contracts
Project-URL: Issues, https://github.com/groupsum/ssot-registry/issues
Keywords: ssot,governance,packs,contracts,metadata,manifest
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: tomli>=2.0.1; python_version < "3.11"

<div align="center">
  <h1>ssot-pack-contracts</h1>
  <p><strong>Shared metadata, manifest, and packaged-document contracts for installable SSOT governance packs.</strong></p>
</div>

<div align="center">
  <a href="https://pypi.org/project/ssot-pack-contracts/"><img src="https://img.shields.io/pypi/v/ssot-pack-contracts?label=PyPI%20version" alt="PyPI version" /></a>
  <a href="https://pypi.org/project/ssot-pack-contracts/"><img src="https://img.shields.io/pypi/pyversions/ssot-pack-contracts?label=Python" alt="Supported Python versions" /></a>
  <a href="https://pepy.tech/project/ssot-pack-contracts"><img src="https://static.pepy.tech/badge/ssot-pack-contracts" alt="Downloads" /></a>
  <a href="https://hits.sh/github.com/groupsum/ssot-registry/"><img src="https://hits.sh/github.com/groupsum/ssot-registry.svg?style=flat-square" alt="Repository hits" /></a>
<!-- ssot-schema-badges:start -->
  <img src="https://img.shields.io/badge/schema_version-0.4.0-blue" alt="schema_version 0.4.0" />
  <img src="https://img.shields.io/badge/migration%20coverage-11%2F11-brightgreen" alt="Migration coverage 11/11" />
<!-- ssot-schema-badges:end -->
</div>

`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](https://pypi.org/project/ssot-core/) or [ssot-cli](https://pypi.org/project/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](https://pypi.org/project/ssot-contracts/) for canonical SSOT schemas, templates, and generated contract metadata
- [ssot-core](https://pypi.org/project/ssot-core/) for registry loading, validation, synchronization, pack ingestion, and mutation APIs
- [ssot-cli](https://pypi.org/project/ssot-cli/) for operator commands such as pack inspection, preflight checks, and sync workflows
- [ssot-registry](https://pypi.org/project/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](https://pypi.org/project/seo-aeo-aieo-governance-pack/) packages SEO, AEO, and AiEO governance ADR/SPEC content.
- [digital-signature-governance-pack](https://pypi.org/project/digital-signature-governance-pack/) packages digital-signature governance ADR/SPEC content.
- [cache-freshness-governance-pack](https://pypi.org/project/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

```bash
python -m pip install ssot-pack-contracts
```

For local development from this repository:

```bash
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:

```python
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:

```json
{
  "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

```python
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:

```python
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:

```python
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](https://pypi.org/project/seo-aeo-aieo-governance-pack/), [digital-signature-governance-pack](https://pypi.org/project/digital-signature-governance-pack/), and [cache-freshness-governance-pack](https://pypi.org/project/cache-freshness-governance-pack/)
- Consumed by: [ssot-core](https://pypi.org/project/ssot-core/) pack ingestion and [ssot-cli](https://pypi.org/project/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](https://pypi.org/project/ssot-cli/) or [ssot-core](https://pypi.org/project/ssot-core/) to inspect, preflight, and synchronize pack content into a governed registry.
