PRD: Registry-backed package handles and official catalog integration

[zack-nova]

Problem Statement

Harness Yard package installation is still awkward for public use because ordinary hyard install examples depend on explicit GitHub repository URLs and branch locators. Runtime Users cannot install a reusable Orbit Package or Harness Package with a stable Package Handle such as acme/docs or docs@0.1.0, and Orbit Authors do not have a clear public registration path for making packages discoverable without exposing Git branch details.

The product already has Package Identity and Package Coordinate parsing concepts, but registry-backed Package Handle resolution is not implemented. Without it, demos and real package sharing remain tied to mutable source details, and users cannot rely on reproducible, reviewed, commit-pinned package installation.

Solution

Add registry-backed Package Handle installation and registration candidate generation to Harness Yard.

Runtime Users should be able to install an Orbit Package or Harness Package with Package Handle Coordinates such as acme/docs, acme/docs@0.1.0, docs, or docs@latest. Harness Yard resolves those handles through a Package Registry into versioned, commit-pinned package locators, then reuses the existing package installation path.

Orbit Authors and Harness Authors should be able to publish installable package revisions, then run a separate hyard registry entry command to generate a submittable Registry Entry Candidate. The official catalog repository owns catalog entries and review policy; the Harness Yard CLI source repository owns schema, resolver behavior, command behavior, package installation semantics, and product documentation.

User Stories

1. As a Runtime User, I want to run hyard install acme/docs, so that I can install a public Orbit Package without knowing its GitHub repository or template branch.
2. As a Runtime User, I want to run hyard install acme/docs@0.1.0, so that I can install a specific reproducible package version.
3. As a Runtime User, I want a bare Package Handle to resolve through an explicit latest dist-tag, so that default installs are controlled by registry truth rather than source branch drift.
4. As a Runtime User, I want registry-backed installation to use commit-pinned locators, so that repeated installs of the same version produce the same package content.
5. As a Runtime User, I want install output to report the requested handle, resolved version, source repo, ref, and commit, so that I can audit what was installed.
6. As a Runtime User, I want registry resolution failures to fail closed, so that Harness Yard does not guess a GitHub URL or install a mutable branch by accident.
7. As a Runtime User, I want yanked versions to require an explicit override, so that I do not accidentally install a version the registry no longer recommends.
8. As a Runtime User, I want blocked versions to be un-installable through registry-backed resolution, so that known-bad package versions cannot be installed by mistake.
9. As a Runtime User, I want exact-version cache use to avoid inferring latest, so that offline or stale cache behavior does not silently choose a moving default.
10. As an Orbit Author, I want to publish an Orbit Package and generate a Registry Entry Candidate with hyard registry entry, so that I can submit a reviewed registry PR without hand-writing locator metadata.
11. As a Harness Author, I want to publish a Harness Package and generate a Registry Entry Candidate, so that composed runtimes can be shared through Package Handles.
12. As a package author, I want Registry Entry Candidates to validate remote repository, ref, commit reachability, package identity, and installability, so that I know my registry submission is reproducible before review.
13. As a package author, I want local-only publication results to produce preview output only, so that I do not submit registry entries that reviewers cannot verify remotely.
14. As a package author, I want Package Handle Coordinates to use namespace/name[@version-or-tag], so that the syntax is readable and does not conflict with @ as the version separator.
15. As a package author, I want Package Handles to remain distinct from Package Identity, so that registry naming can differ from the package's installed identity when necessary.
16. As a package author, I want ordinary public handles to be namespaced by source repository owner or organization, so that global name collisions do not block package sharing.
17. As a maintainer, I want unnamespaced handles to remain curated, so that public demos can use short handles without opening global name squatting.
18. As a maintainer, I want the official catalog data to live outside the CLI source repository, so that third-party package submissions do not clutter product development history.
19. As a maintainer, I want the CLI source repository to own registry schema and resolver behavior, so that product behavior remains versioned with the CLI.
20. As a maintainer, I want Registry Entry Candidates generated by the CLI to follow the same schema that install resolution consumes, so that registration and installation do not drift.
21. As a maintainer, I want validation errors to distinguish handle parsing, registry lookup, dist-tag resolution, status gating, remote reachability, and package installability, so that users get actionable recovery guidance.
22. As a maintainer, I want registry-backed install records to preserve complete provenance, so that uninstall, audit, and future diagnostics can explain the package source.
23. As a documentation reader, I want quickstart and release-surface examples to use Package Handles once the registry is supported, so that public docs no longer teach GitHub branch locators as the ordinary path.
24. As a test maintainer, I want registry parsing and resolution logic to be tested in isolation, so that install behavior is not only covered by slow end-to-end tests.
25. As a release maintainer, I want release-surface smoke tests to cover registry-backed install help and examples, so that the public command contract stays coherent.

Implementation Decisions

• Build a dedicated Package Handle Coordinate parser rather than reusing Package Identity parsing directly. Package Handle Coordinates are registry-facing selectors and may include a namespace, version, or dist-tag.
• Add a Package Registry schema model that can represent handles, dist-tags, version entries, status, locator metadata, and minimal validation evidence.
• Add a registry resolver module with a small interface: resolve a Package Handle Coordinate into package type, package name, resolved version, source repository, ref, commit, and status facts.
• Keep registry resolver behavior separate from catalog review policy. The CLI source repository owns schema and resolution behavior; the official catalog repository owns catalog data and review decisions.
• Add an install-source bridge that converts resolved registry locators into the existing external Git install path, preserving install provenance.
• Extend hyard install to recognize Package Handle Coordinates while preserving explicit Git locator and explicit source forms.
• Keep hyard registry entry separate from hyard publish; publication creates installable package revisions, while registry entry generation creates submittable catalog candidates.
• Make submittable Registry Entry Candidate generation validate remote repository availability, ref existence, commit reachability, package identity consistency, and installability.
• Allow local-only registry entry preview output, but mark it non-submittable and do not present it as review-ready.
• Implement status gates for deprecated, yanked, and blocked versions. Deprecated versions warn, yanked versions require explicit override, and blocked versions cannot install.
• Fail closed when registry resolution is unavailable. Do not guess GitHub URLs, source default branches, or package repositories from handle strings.
• Allow cache use only for exact version resolution. Do not infer latest from cached data when current registry resolution is unavailable.
• Preserve registry provenance in install records and JSON/text command output.
• Update public documentation once registry-backed handles are supported; until then, explicit GitHub locators may remain documented as the current fallback.
• Keep the official registry catalog repository as a separate repository with its own design memory and ADRs for catalog-specific operations.

Testing Decisions

• Good tests should prove that Package Handle Coordinates are parsed independently from Package Identity and Git locator forms.
• Good tests should prove that namespace/name[@version-or-tag] is accepted and npm-style @namespace/name is rejected with clear guidance.
• Test the registry schema parser and validator with valid handles, invalid handles, missing dist-tags, immutable version entries, yanked versions, blocked versions, and malformed locator data.
• Test the resolver as a deep module with in-memory catalog fixtures so dist-tag selection, exact-version selection, status gates, and cache behavior are fast and deterministic.
• Test install integration with existing remote template fixtures to ensure resolved locators reuse the existing external Git install path.
• Test that registry-backed install records and JSON/text output include requested coordinate, resolved version, registry source, repo, ref, and commit.
• Test hyard registry entry candidate generation from published Orbit Package and Harness Package evidence.
• Test that submittable candidate generation fails when remote ref, commit reachability, package identity, or installability validation fails.
• Test local-only candidate preview behavior separately from submittable candidate behavior.
• Test fail-closed paths for unavailable registry resolution and ensure no GitHub URL guessing occurs.
• Test yanked and blocked install behavior, including explicit yanked override and blocked no-override behavior.
• Extend release-surface or quickstart smoke coverage when public docs, help output, or install examples switch to registry-backed handles.

Out of Scope

• Arbitrary tool, service, plugin, CLI, or Agent Framework registration.
• A hosted account system, OAuth namespace claims, or web registration UI.
• Default self-hosted registry discovery.
• Marketplace features such as ratings, download counts, broad safety labels, signatures, or SBOM requirements.
• Automatic registry PR creation from hyard.
• Mutable branch-backed default install behavior.
• Changing Package Uninstallation semantics.
• Replacing explicit Git source installation as an escape hatch.

Further Notes

• Relevant product decision record: ADR 0004 Package registry product integration.
• Relevant catalog decision record: the official catalog repository's ADR 0001 Official catalog bootstrap.
• Current product documentation says public demos should use explicit GitHub locators until registry-backed Package Handles are part of the public release surface.
• The implementation should preserve the Git-native model: one repository, normal Git commits as history, and explicit Git argument lists.
• The registry catalog repository created during planning is local at /Users/zack/Code/Vocation/hyard-registry; its remote publication is separate from this PRD.

Blocked by

• Install exact Package Handle Coordinates from a Git registry #91 - Install exact Package Handle Coordinates from a Git registry.
• Resolve latest and curated Package Handles with global cache semantics #92 - Resolve latest and curated Package Handles with global cache semantics.
• Enforce package-level registry status gates during install #93 - Enforce package-level registry status gates during install.
• Preserve registry provenance in install output and records #94 - Preserve registry provenance in install output and records.
• Generate Orbit Registry Entry Candidates #95 - Generate Orbit Registry Entry Candidates.
• Generate Harness Registry Entry Candidates #96 - Generate Harness Registry Entry Candidates.
• Document package-handle install and registry entry release surface #97 - Document package-handle install and registry entry release surface.

Resume this parent PRD after the child issue set is resolved, then decide whether the PRD is complete or a remaining follow-up slice is needed.

[zack-nova]

Registry Source Contract Decisions

Decision snapshot from the HITL discussion for the registry-backed package handle work.

• Official catalog source: zack-nova/hyard-registry; resolver must support any Git remote as a registry source.
• Public registration model: catalog-as-code through reviewed registry entry candidates. No hosted registration service, OAuth/account system, automatic registration API, or automatic PR creation in the first version.
• Catalog format: YAML with schema version. Use namespace-level indexes rather than one file per package. Namespace ownership is explicit.
• Namespace owners: Git-platform user/org identities.
• Coordinate syntax: namespace/name[@version-or-tag] and curated name[@version-or-tag]; case-insensitive; normalize before resolution; no npm-style @namespace/name.
• Bare handles: reserved for curated aliases only. Ordinary authors register namespace/name; curated aliases point at namespaced package handles and do not copy full version locator metadata.
• Dist-tags: bare handle is equivalent to @latest; latest must be explicit registry data and must not be inferred from Git branches, newest registry merge, or highest SemVer.
• Status: package-level. Deprecated warns, yanked requires explicit override, blocked cannot install.
• Commit pinning: installs resolve to commit SHA; branch/tag refs are provenance or discovery inputs, not final install locators.
• Cache: user-level global cache, npm/pip style, with HYARD_CACHE_DIR override. Exact versions may be cached. Bare/latest should refresh when registry is available; when unavailable, a previously verified cached resolution may be used with a warning.
• Local override: supported for development, tests, and private catalog experiments without changing the official catalog boundary.
• Registry entry candidates: orbit and harness commands output the same YAML candidate schema. Candidate records target path, package type, package identity, source repository, ref, commit SHA, status, and validation evidence. Local-only package results are preview-only. Registry CI must revalidate and must not trust local evidence as authoritative.
• Repository boundary: harnessyard owns schema, parser, resolver, installer bridge, candidate generation, and product docs; the official catalog repo owns catalog entries, namespace ownership, curated handles, review policy, and CI validation.

These decisions are also recorded in CONTEXT.md and docs/adr/0004-package-registry-product-integration.md.

[zack-nova]

This was generated by AI during triage.

Triage Notes

Corrected Current Decision

This parent PRD was previously recorded as needing a split, but the child implementation issues already exist. #90 should remain state:blocked, not state:needs-split, while those child issues progress.

Confirmed

• PRD: Registry-backed package handles and official catalog integration #90 has exactly one state label (state:blocked) and exactly one type label (type:feature).
• The existing child issues declare ## Parent as PRD: Registry-backed package handles and official catalog integration #90: Install exact Package Handle Coordinates from a Git registry #91, Resolve latest and curated Package Handles with global cache semantics #92, Enforce package-level registry status gates during install #93, Preserve registry provenance in install output and records #94, Generate Orbit Registry Entry Candidates #95, Generate Harness Registry Entry Candidates #96, and Document package-handle install and registry entry release surface #97.
• No defect reproduction is applicable because this is feature/PRD triage, not a bug report.

Blocked By

• Install exact Package Handle Coordinates from a Git registry #91 - Install exact Package Handle Coordinates from a Git registry.
• Resolve latest and curated Package Handles with global cache semantics #92 - Resolve latest and curated Package Handles with global cache semantics.
• Enforce package-level registry status gates during install #93 - Enforce package-level registry status gates during install.
• Preserve registry provenance in install output and records #94 - Preserve registry provenance in install output and records.
• Generate Orbit Registry Entry Candidates #95 - Generate Orbit Registry Entry Candidates.
• Generate Harness Registry Entry Candidates #96 - Generate Harness Registry Entry Candidates.
• Document package-handle install and registry entry release surface #97 - Document package-handle install and registry entry release surface.

Resume Path

After #91-#97 are resolved, revisit #90 and decide whether the parent PRD is complete or whether a remaining follow-up slice is needed.