actors-spec/docs/actor-registry-standard.md

The Package Registry Standard

Version: 1.0.0 Status: Normative

---

0. Document Conventions

This document uses the following conventions to specify normative requirements:

• MUST, REQUIRED, SHALL indicate an absolute requirement.
• MUST NOT, SHALL NOT indicate an absolute prohibition.
• SHOULD, RECOMMENDED indicate that there may exist valid reasons in particular circumstances to ignore a particular requirement, but the full implications must be understood and carefully weighed.
• SHOULD NOT, NOT RECOMMENDED indicate that there may exist valid reasons in particular circumstances when the particular behavior is acceptable, but the full implications should be understood and the case carefully weighed.
• MAY, OPTIONAL indicate that an item is truly optional.

Code and configuration examples are presented in YAML 1.2 syntax. Internal identifiers, types, and values are presented in monospaced font.

A "compliant implementation" is any software that provides package registry services in conformance with the requirements of this document.

The terms "package", "registry", "client", and "server" are used throughout this document to refer to packages, package registries, registry clients, and registry servers respectively.

---

1. Introduction

1.1 Purpose

This document defines the Package Registry Standard: a protocol and data model for storing, retrieving, and managing versioned packages of AI components. A Package Registry provides a centralized system for discovering, sharing, and distributing reusable AI building blocks including actors, graphs, agents, templates, skills, and other component types.

1.2 Scope

This standard normatively defines:

1. The structural grammar and syntax of package identifiers.
2. The complete set of allowed package types and their content-addressed storage format.
3. The versioning scheme for packages including semantic versioning and alias resolution.
4. The reference formats for declaring dependencies between packages.
5. The canonicalization process for ensuring content-addressable uniqueness.
6. The API endpoints and request/response formats for registry operations.
7. The authentication and authorization mechanisms.
8. The discovery and browsing capabilities.
9. The package metadata schema.
10. The caching and assembly mechanisms for composite packages.

This standard does NOT define:

1. Specific programming-language bindings or SDKs.
2. Internal storage implementations or database schemas.
3. User interface designs or web application layouts.
4. Package build tools or publishing workflows beyond the API requirements.
5. Specific security implementations beyond authentication requirements.

1.3 Conformance

A compliant implementation MUST:

1. Accept any well-formed package that conforms to this standard and reject any document that does not.
2. Implement all required API endpoints with the specified request/response formats.
3. Support at least all defined package types as defined in this document.
4. Apply the canonicalization rules in §5 and signal errors for invalid packages.
5. Support the version resolution mechanism described in §4.2.
6. Treat all reserved identifiers (§7) appropriately.

A compliant implementation MAY:

1. Provide additional package types beyond those defined here, provided they do not conflict with the names defined in this standard.
2. Implement additional API endpoints for enhanced functionality.
3. Support alternative authentication mechanisms beyond those required.
4. Optimize storage or retrieval where the optimization is not observable through the defined API.

---

2. Terminology

Term	Definition
Package	A content-addressed, versioned unit of AI components conforming to a specific type schema.
Registry	A service implementing this standard that stores and serves packages.
Client	Software that interacts with a registry to publish or retrieve packages.
Server	The registry implementation providing the API endpoints.
Package ID	A globally unique identifier for a package in the format pkg_<type>_<40-hex-sha1>.
Reference	A string that identifies a package, which may be resolved to a concrete Package ID.
Version	A semantic version string or alias that identifies a specific package revision.
Alias	A mutable reference that resolves to a concrete version (e.g., latest, v1.x).
Canonical Form	The normalized, content-addressed representation of a package used for SHA1 computation.
Assembly	The process of resolving and combining dependencies into a complete package document.
Namespace	A logical grouping of packages under a shared ownership context.

---

3. Document Structure

3.1 Package Format

A package MUST be a valid YAML 1.2 document encoded in UTF-8. The top-level YAML value MUST be a mapping (dictionary). Documents that are not mappings, or that fail to parse as YAML, MUST be rejected with an error.

3.2 Package Types

The following table enumerates all permitted package types. Each type defines the structure and semantics of packages of that kind:

Type	Prefix	Description
actor	pkg_act_	Actor configuration documents conforming to the Actor Configuration Standard.
graph	pkg_grh_	Graph route definitions that can be used as components in larger systems.
stream	pkg_str_	Stream route definitions for reactive processing pipelines.
agent	pkg_agt_	Agent definitions that can be referenced in actor configurations.
template	pkg_tpl_	Reusable template definitions for actors, graphs, streams, or agents.
skill	pkg_skl_	Skill packages defining capabilities for AI agents.
mcp	pkg_mcp_	MCP (Model Connector Protocol) server definitions.
lsp	pkg_lsp_	LSP (Language Server Protocol) service definitions.

3.3 Minimum Valid Package

The minimum valid package MUST contain at least:

1. All required fields for its package type as defined by the respective standards.
2. A name field identifying the package within its namespace.
3. A description field explaining the package's purpose.

---

4. Versioning Scheme

4.1 Version Formats and Semantics

Format	Type	Behavior	Example
vX.Y.Z	Immutable Concrete	Always points to same SHA1	v3.2.1 → always pkg_act_a1b2c3...
vX.Y.x	Mutable Range Alias	Points to latest Z in X.Y.* series	v3.2.x → points to latest v3.2.Z
vX.x	Mutable Major Alias	Points to latest version with major X	v3.x → points to latest v3..
vx	Mutable Global Alias	Synonymous with latest	vx → points to globally latest version
latest	Mutable Global Alias	Synonymous with vx	latest → points to globally latest version

4.2 Version Resolution Logic

When resolving a version reference:

1. If the version is immutable (concrete), resolve directly to the corresponding package ID.
2. If the version is mutable (alias):
   • Retrieve all published versions for the package namespace/name.
   • Filter to only concrete versions that match the alias pattern.
   • Sort matching versions semantically (newest first).
   • Return the latest/best matching version.

---

5. Package Identifiers

5.1 Package ID Format

Every package is identified by a globally unique identifier in the format:

pkg_<type>_<40-hex-sha1>

Where:

• pkg_ is a fixed prefix
• <type> is one of the defined package type prefixes (§3.2)
• <40-hex-sha1> is exactly 40 lowercase hexadecimal characters representing a SHA1 hash

5.2 Package ID Generation

A Package ID MUST be generated by:

1. Canonicalizing the package content according to §6.
2. Computing the SHA1 hash of the canonical form.
3. Formatting as pkg_<type>_<sha1> where type is determined by the package content.

5.3 Reference Formats

Packages are referenced using the following formats:

# Registry reference with version - external package server
mcp_server: "registry.cleverrouter.com:acme/web_search@latest"
skill_ref: "skills.example.com:code_analysis@2.3.1"

# SHA1 reference - direct ID reference
template_ref: "ID:pkg_tpl_a1b2c3d4e5f67890abcdef1234567890abcdef"

# All references can omit version (defaults to @latest)
agent_no_version: "registry.cleverrouter.com:simple/agent"  # Same as @latest

---

6. Canonicalization

6.1 Canonical Form Requirements

Every package MUST have a canonical form that:

1. Is deterministically generated from the package content.
2. Uses UTF-8 encoding with NFC normalization for all string values.
3. Sorts dictionary keys lexicographically.
4. Removes lifecycle fields that record when content was authored (e.g., version, release_date).
5. Resolves all internal references to SHA1 IDs.

6.2 Canonicalization Process

The canonicalization process MUST:

1. Parse the package YAML into a structured representation.
2. Normalize string values using Unicode NFC normalization.
3. Sort dictionary keys lexicographically.
4. Remove lifecycle fields.
5. Resolve internal references to concrete SHA1 IDs.
6. Serialize to RFC-8785 canonical JSON format.

6.3 Dependency Resolution

During canonicalization, all references within the package MUST be resolved:

1. References to other packages in the same bundle are resolved first.
2. External registry references are fetched and resolved to their concrete Package IDs.
3. All resolved dependencies are recorded in the canonical form's metadata.

---

7. Reserved Names

The following names are reserved by this standard and MUST NOT be used for user-defined package types or identifiers:

7.1 Type Prefixes

All prefixes defined in §3.2 are reserved for their specified semantics.

7.2 Version Aliases

The version aliases latest, vx, and patterns ending in .x are reserved for the standard version resolution mechanism.

7.3 Reference Schemes

The reference schemes ID:, registry:, and local: are reserved for their specified semantics.

---

8. API Specification

8.1 Overview

A compliant registry implementation MUST provide the following HTTP API endpoints:

Endpoint	Method	Purpose
/packages/{package_id}	GET	Retrieve raw package content by ID
/{package_type}/{namespace}/{name}	GET	Resolve a package by type, namespace, name, and version
/publish	POST	Publish a new package version
/browse	GET	Browse published packages with optional filters
/.well-known/cleverrouter-packages	GET	Registry discovery endpoint

8.2 Package Retrieval

8.2.1 Get Package by ID

GET /packages/{package_id}

Returns the raw package content for the specified package ID.

Response:

{
  "content": "<YAML string>"
}

8.2.2 Resolve Package

GET /{package_type}/{namespace}/{name}?version={version}

Resolves a package reference to its concrete Package ID.

Response:

{
  "package_id": "pkg_act_a1b2c3d4e5f67890abcdef1234567890abcdef",
  "type": "actor"
}

8.3 Publishing

8.3.1 Publish Package

POST /publish

Request:

{
  "package_id": "pkg_act_a1b2c3d4e5f67890abcdef1234567890abcdef",
  "namespace": "example",
  "name": "my-actor",
  "version": "v1.0.0"
}

Response:

{
  "version_id": "pver_...",
  "message": "Published successfully"
}

8.4 Discovery

8.4.1 Browse Packages

GET /browse?type={type}&namespace={namespace}

Returns a list of published packages matching the filters.

Response:

{
  "packages": [
    {
      "id": "pkg_act_...",
      "type": "actor",
      "name": "my-actor",
      "description": "An example actor package",
      "namespace": "example",
      "version_count": 3,
      "created_at": "2026-05-25T10:00:00Z"
    }
  ],
  "count": 1
}

8.4.2 Registry Discovery

GET /.well-known/cleverrouter-packages

Returns metadata about the registry implementation.

Response:

{
  "name": "CleverRouter Package Registry",
  "version": "1.0.0",
  "supported_types": ["actor", "graph", "stream", "agent", "template", "skill", "mcp", "lsp"],
  "authentication": ["anonymous", "api_key"],
  "features": ["semantic_versioning", "mutable_aliases"]
}

---

9. Authentication and Authorization

9.1 Anonymous Access

Registries MUST support anonymous read access to public packages.

9.2 Authenticated Access

For publishing or accessing private packages, registries MAY require authentication using:

1. API key tokens passed in the Authorization header.
2. OAuth2 bearer tokens.
3. Other mutually agreed-upon authentication mechanisms.

9.3 Authorization Model

Registries MUST enforce the following authorization rules:

1. Only authenticated users MAY publish packages.
2. Package owners control publishing permissions for their namespaces.
3. Private packages are only accessible to authorized users.
4. Public packages are readable by all users (anonymous or authenticated).

---

10. Caching and Assembly

10.1 Content-Addressed Storage

Packages MUST be stored using content-addressed storage where:

1. The key is the full Package ID.
2. The value is the canonical YAML representation.
3. Storage is immutable - once written, content cannot change.

10.2 Assembly Cache

For packages with dependencies, registries SHOULD maintain an assembly cache that:

1. Stores fully resolved package documents with dependencies inlined.
2. Uses LRU eviction policies to manage storage space.
3. Invalidates cached assemblies when dependencies change.

10.3 Client-Side Caching

Clients SHOULD implement caching mechanisms that:

1. Store previously retrieved packages locally.
2. Validate cached content using Package IDs.
3. Refresh cached content based on TTL or version updates.

---

11. Validation Rules

The following rules MUST be enforced for package operations:

11.1 Package Validation

1. The package document MUST parse as valid YAML 1.2.
2. The top-level document MUST be a mapping.
3. The package MUST conform to the structural requirements of its declared type.
4. All references MUST resolve to valid Package IDs.
5. The canonical form MUST produce a consistent SHA1 hash.

11.2 Publishing Validation

1. Only authenticated users MAY publish packages.
2. Package IDs MUST be unique - duplicates SHALL be rejected.
3. Version strings MUST conform to the defined format.
4. Namespace ownership MUST be verified for publishing.
5. Dependencies MUST exist in the registry or be published simultaneously.

11.3 Reference Validation

1. All package references MUST resolve to existing packages.
2. Circular dependencies MUST be detected and rejected.
3. Version constraints on dependencies MUST be satisfiable.

---

12. Security Model

12.1 Package Integrity

All packages MUST be content-addressed to ensure:

1. Tamper evidence - any change to package content changes its ID.
2. Deduplication - identical packages resolve to the same ID.
3. Immutability - published packages cannot be altered.

12.2 Transport Security

All communication with registry servers MUST use HTTPS in production environments.

12.3 Access Control

Registries MUST implement access control that:

1. Separates public and private packages.
2. Controls publishing permissions by namespace ownership.
3. Supports authentication for protected operations.
4. Logs security-relevant events for audit purposes.

---

13. Error Handling

13.1 Error Response Format

All error responses MUST follow this format:

{
  "error": {
    "type": "<error_type>",
    "message": "<human_readable_message>",
    "details": { /* optional additional details */ }
  }
}

13.2 Defined Error Types

Error Type	HTTP Status	Description
PackageNotFound	404	The requested package does not exist
InvalidPackageId	400	The provided Package ID format is invalid
VersionNotFound	404	The requested version does not exist
ValidationError	400	The package failed validation
AuthenticationRequired	401	Authentication is required for this operation
AccessDenied	403	Access to the requested resource is denied
Conflict	409	The request conflicts with existing data
InternalServerError	500	An unexpected error occurred server-side

---

14. Compliance Test Vectors

A compliant implementation SHOULD be tested against (at minimum) the following classes of test vectors:

1. Package ID Generation: Valid and invalid Package ID formats.
2. Canonicalization: Various package types with different content.
3. Version Resolution: Concrete versions and mutable aliases.
4. Reference Resolution: Different reference formats and edge cases.
5. API Operations: All required endpoints with valid and invalid inputs.
6. Authentication: Access control for public/private packages.
7. Error Conditions: Proper error responses for all failure modes.
8. Caching: Cache behavior for updated and unchanged packages.

---

15. Versioning of This Standard

This document is Version 1.0.0 of the Package Registry Standard. Future revisions:

• A patch version (1.0.x) corrects errors and clarifies semantics without changing required behavior.
• A minor version (1.x.0) adds new optional features without breaking conformance of existing implementations.
• A major version (x.0.0) introduces breaking changes; non-backward-compatible.

Conformance MUST be declared against a specific version of this standard. Implementations MAY support multiple major versions concurrently.