Epic: Package Registry Client — Support Package Registry Standard v1.0.0 #22

New issue

Open

opened 2026-06-05 17:33:15 +00:00 by CoreRasurae · 0 comments

CoreRasurae commented

2026-06-05 17:33:15 +00:00

Member

Metadata

Commit Message: feat(registry): implement Package Registry Standard v1.0.0 client

Background and context

The Package Registry Standard v1.0.0 (per actor-registry-standard.md) defines a protocol and data model for storing, retrieving, and managing versioned packages of AI components. This Epic covers the implementation of a compliant client — not a server — that fetches, resolves, caches, and integrates registry packages into the CleverActors template system.

Expected behavior

When complete, templates and Actor configurations will be able to reference external packages via registry references (server:namespace/name@version), direct SHA-1 IDs (ID:pkg_act_<40-hex>), and local references. Internally all IDs are SHA-1; debug traces carry the original user-specified reference.

Acceptance criteria

All child issues are closed AND:

src/cleveractors/registry/ module exists with types, client, canonicalizer, resolver, exceptions, cache
A template referencing registry.example.com:acme/helper@v1.0.0 resolves, fetches, and instantiates correctly
Canonicalization produces deterministic SHA-1 per the standard
HTTP client uses httpx for async registry operations
97%+ coverage on all new registry modules
nox full suite passes

Subtasks

Core data types (PackageType, PackageId, PackageReference, PackageContent)
Registry HTTP client using httpx (async, 4 endpoints, error mapping)
Canonicalization engine (NFC, key sorting, RFC-8785, SHA-1)
Reference resolution (parse refs, version aliases, local scheme)
Template system alignment (extend TemplateType, integrate PackageReference)
Client-side caching (LRU, TTL, ID validation)
Exception hierarchy (RegistryError + 8 typed errors)
BDD features + test vectors (mock server, canonicalization matrices)

Definition of Done

This Epic is complete when:

All subtasks above are completed and checked off.
All child issues are closed and their Definition of Done criteria are met.
The src/cleveractors/registry/ module is fully implemented and tested.
nox returns all-green.
A stakeholder can demonstrate a template using a registry reference that resolves correctly.

Dependency graph

#22 Epic
├── #23 Core types
│   ├── #25 Canonicalization
│   ├── #26 Reference resolution
│   └── #29 Exceptions
├── #24 HTTP client
├── #27 Template alignment
├── #28 Caching
└── #30 BDD features

New module structure

src/cleveractors/registry/
    __init__.py          # Public exports
    types.py             # PackageType, PackageId, PackageReference, PackageContent
    client.py            # RegistryClient (async httpx)
    canonical.py          # Canonicalizer (SHA-1 computation)
    resolver.py           # ReferenceResolver (parse + version resolution)
    exceptions.py         # Error type hierarchy
    cache.py              # Client-side caching (TTL, LRU)

## Metadata Commit Message: feat(registry): implement Package Registry Standard v1.0.0 client ## Background and context The Package Registry Standard v1.0.0 (per `actor-registry-standard.md`) defines a protocol and data model for storing, retrieving, and managing versioned packages of AI components. This Epic covers the implementation of a compliant **client** — not a server — that fetches, resolves, caches, and integrates registry packages into the CleverActors template system. ## Expected behavior When complete, templates and Actor configurations will be able to reference external packages via registry references (`server:namespace/name@version`), direct SHA-1 IDs (`ID:pkg_act_<40-hex>`), and local references. Internally all IDs are SHA-1; debug traces carry the original user-specified reference. ## Acceptance criteria All child issues are closed AND: - `src/cleveractors/registry/` module exists with types, client, canonicalizer, resolver, exceptions, cache - A template referencing `registry.example.com:acme/helper@v1.0.0` resolves, fetches, and instantiates correctly - Canonicalization produces deterministic SHA-1 per the standard - HTTP client uses `httpx` for async registry operations - 97%+ coverage on all new registry modules - `nox` full suite passes ## Subtasks - [ ] Core data types (PackageType, PackageId, PackageReference, PackageContent) - [ ] Registry HTTP client using httpx (async, 4 endpoints, error mapping) - [ ] Canonicalization engine (NFC, key sorting, RFC-8785, SHA-1) - [ ] Reference resolution (parse refs, version aliases, local scheme) - [ ] Template system alignment (extend TemplateType, integrate PackageReference) - [ ] Client-side caching (LRU, TTL, ID validation) - [ ] Exception hierarchy (RegistryError + 8 typed errors) - [ ] BDD features + test vectors (mock server, canonicalization matrices) ## Definition of Done This Epic is complete when: - All subtasks above are completed and checked off. - All child issues are closed and their Definition of Done criteria are met. - The `src/cleveractors/registry/` module is fully implemented and tested. - `nox` returns all-green. - A stakeholder can demonstrate a template using a registry reference that resolves correctly. ## Dependency graph ``` #22 Epic ├── #23 Core types │ ├── #25 Canonicalization │ ├── #26 Reference resolution │ └── #29 Exceptions ├── #24 HTTP client ├── #27 Template alignment ├── #28 Caching └── #30 BDD features ``` ## New module structure ``` src/cleveractors/registry/ __init__.py # Public exports types.py # PackageType, PackageId, PackageReference, PackageContent client.py # RegistryClient (async httpx) canonical.py # Canonicalizer (SHA-1 computation) resolver.py # ReferenceResolver (parse + version resolution) exceptions.py # Error type hierarchy cache.py # Client-side caching (TTL, LRU) ```

Rows
Columns