tegwick
5f47da8036
Search, versions, manifests, archives and the index, over HTTP.
The route shape is the decision worth recording. Package ids contain `/`, so
the obvious /packages/{id}/{version} is ambiguous under a greedy path
parameter. Rather than invent an HTTP-specific identifier, the routes speak the
format's own <registry>:<id>@<version> syntax and parse it — `:` and `@` are
both legal in a path segment, and each route keeps a distinct prefix so
greediness cannot swallow a neighbouring one. The API therefore exercises
section 3.2's reference notation instead of working around it.
A bare id present in more than one registry returns 409 with the candidates,
never a guess. 409 rather than 300 because the request is answerable once the
caller says which registry they meant. Omitting a version applies section
17.1's selector rules, so a prerelease is never chosen implicitly.
Validation is delegated to reference/, installed into the service environment
rather than reimplemented. One validator means the service and the CLI cannot
disagree about what a valid package is; a service accepting something the CLI
rejects would be the divergence this project exists to prevent. Importing it is
not changing it — reference/ stays the dependency-light conformance witness.
Storage keeps the format's distinctions: an immutable package version, its
files as content rather than parsed rows, and an index entry recording arrival.
Only reserved paths and manifest-referenced files are stored (section 2), and a
re-publish of identical content is accepted while different content under the
same id@version is a conflict (section 17).
Handles a real test-vs-production difference: SQLite autoincrements INTEGER
PRIMARY KEY only, never BIGINT, so the SQLite-backed tests could not insert a
row. BigInteger().with_variant(Integer, "sqlite") keeps BIGINT on PostgreSQL
while letting the tests exercise the same models and migration.
Verified live against a seeded store holding this repo's examples and four
helix-forge prompt packages. Service tests 11 -> 22.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Bjefh8NUiEiahN4JLwoSKM
Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 388925@bnt-lap001
Assistant-Session: 3507023f-e0fd-4a1e-9d90-a0d4217d1502
204 lines
8.3 KiB
Markdown
204 lines
8.3 KiB
Markdown
---
|
|
id: CANP-WP-0006
|
|
type: workplan
|
|
title: "Hosted registry and index service"
|
|
domain: agents
|
|
repo: canned-prompts
|
|
status: active
|
|
owner: codex
|
|
topic_slug: practice
|
|
created: "2026-09-06"
|
|
updated: "2026-09-06"
|
|
state_hub_workstream_id: "70c069e9-7abe-569a-aee2-ffcd15e8970d"
|
|
---
|
|
|
|
# Hosted registry and index service
|
|
|
|
Toward a production deployment on railiance01 as `rapp-canned-prompts`.
|
|
|
|
**Sequencing finding.** A `rapp-*` repo packages and operates a deployable its
|
|
`ownership_repo` already produces — `declarations/rapp.yaml` pins
|
|
`upstream_components.version` to a container digest. `canned-prompts` has no
|
|
deployable: a CLI module with no HTTP surface, no image, no database. A rapp
|
|
whose `upstream_components` points at nothing is a stub that tells the fleet's
|
|
tooling a deployment exists when none does. The service comes first.
|
|
|
|
**Decisions (operator, 2026-09-06):**
|
|
|
|
- *Hosted registry plus index* is the v1 surface. § 20 already permits an HTTP
|
|
registry and § 20.3's index is the query surface, so this validates INTENT
|
|
principle 10's "registry-ready" claim rather than inventing a new concept.
|
|
- *The service lives in `canned-prompts`*, so `rapp.yaml` gets
|
|
`ownership_repo: canned-prompts` — the `sbom-nexus` shape, where product
|
|
ownership stays out of the operations repo.
|
|
- *Platform service, tenant-keyed regardless.* Deployed as a platform service
|
|
like `sbom-nexus`, but all owned data is keyed by tenant from the first
|
|
migration. `business-app-service-contract_v0.1` § 1.3 makes that mandatory so
|
|
a later consolidation is a data-copy rather than a rewrite; a collaborative
|
|
prompting platform will need it, and retrofitting is the expensive path.
|
|
- *Service first, rapp when there is a digest to pin.*
|
|
|
|
**Stack**, matching `state-hub` and `sbom-nexus`: FastAPI, uvicorn, SQLAlchemy,
|
|
Alembic, Pydantic, PostgreSQL. `RailianceAppDeploymentGuide.md` additionally
|
|
requires unauthenticated `/healthz` and `/readyz`.
|
|
|
|
**Boundary.** The service hosts packages; it does not become an agent runtime.
|
|
`INTENT.md`'s deliberate boundary still holds — no model execution, no
|
|
orchestration. Rendering stays deterministic, and `derive` stays a declaration
|
|
the service does not satisfy.
|
|
|
|
## Service skeleton and health surface
|
|
|
|
```task
|
|
id: CANP-WP-0006-T01
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "6e4178f0-a431-59de-8bd1-fb5b2de95302"
|
|
```
|
|
|
|
A `service/` package inside this repo: FastAPI application factory, settings
|
|
via pydantic-settings, and the health surface the deployment guide requires —
|
|
unauthenticated `/healthz` and `/readyz`, plus `/state/health` for consistency
|
|
with `state-hub` and `sbom-nexus`.
|
|
|
|
`/readyz` must actually check the database, not return 200 unconditionally. A
|
|
readiness probe that cannot fail is a liveness probe with a misleading name.
|
|
|
|
Keep `reference/` untouched. It is the format's conformance witness and must
|
|
stay dependency-light; the service is a separate consumer of the same package
|
|
semantics.
|
|
|
|
**Done.** `service/` with a FastAPI factory, pydantic-settings config, and the
|
|
three endpoints. `CANNED_PROMPTS_DATABASE_URL` has no default, so a
|
|
misconfigured service refuses to start rather than quietly using a local
|
|
database.
|
|
|
|
**Bug found by its own test.** `check_readiness` first caught every failure in
|
|
one `except` and reported "database unreachable". An unmigrated but perfectly
|
|
reachable database therefore reported a connection problem — sending an
|
|
operator to credentials and networking when the fix was `alembic upgrade`.
|
|
Connectivity and schema are now checked separately.
|
|
|
|
## Tenant-keyed schema and first migration
|
|
|
|
```task
|
|
id: CANP-WP-0006-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "bc0e4a49-63b1-5fa1-9ec9-5ed0f505baa1"
|
|
```
|
|
|
|
Alembic migration `0001` creating the store. Every table holding owned data
|
|
carries a tenant key from this migration onward — packages, versions, and index
|
|
entries — per the service contract § 1.3. No business logic may assume it is
|
|
the only tenant (§ 1.4).
|
|
|
|
Model the three things the format already distinguishes, and do not conflate
|
|
them:
|
|
|
|
- **package version** — immutable content addressed by `<id>@<version>`
|
|
(§ 17), scoped to a registry because identity is registry-scoped (§ 3.2);
|
|
- **index entry** — how a version arrived in this store (§ 20.3): source,
|
|
method, `included_at` which is never overwritten, `last_seen_at`;
|
|
- **manifest fields** worth indexing for discovery — name, summary, tags,
|
|
license, type.
|
|
|
|
Store package files as content, not as rows per file.
|
|
|
|
**Done.** Migration `0001` creates `package_versions`, `package_files` and
|
|
`index_entries`; a test asserts every table in the metadata carries `tenant`, so
|
|
adding an unkeyed table fails the suite rather than being noticed at
|
|
consolidation time. Uniqueness is `(tenant, registry, package_id, version)`.
|
|
|
|
## Read API
|
|
|
|
```task
|
|
id: CANP-WP-0006-T03
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "0ae11e65-68b0-543c-b8fa-f3188a4d239a"
|
|
```
|
|
|
|
`GET /packages` (search over id, name, summary, tags), `GET /packages/{id}`
|
|
(versions), `GET /packages/{id}/{version}` (manifest),
|
|
`GET /packages/{id}/{version}/archive` (the package files), and
|
|
`GET /index` (§ 20.3 entries).
|
|
|
|
Ambiguity is reported, never guessed (§ 3.2): a bare id matching packages from
|
|
more than one registry returns the candidates, not a choice.
|
|
|
|
**Done**, with the route shape worth recording. Package ids contain `/`, so the
|
|
obvious `/packages/{id}/{version}` is ambiguous under a greedy path parameter.
|
|
Rather than invent an HTTP-specific identifier, the routes speak the format's
|
|
own `<registry>:<id>@<version>` syntax and parse it — `:` and `@` are both legal
|
|
in a path segment, each route keeps a distinct prefix, and the API therefore
|
|
tests § 3.2's reference notation rather than working around it.
|
|
|
|
Ambiguity returns **409 with the candidates**, not 300: the request is
|
|
answerable once the caller says which registry they meant. Omitting a version
|
|
applies § 17.1's selectors, so a prerelease is never chosen implicitly.
|
|
|
|
Validation is delegated to `reference/`, installed into the service
|
|
environment rather than reimplemented. One validator means the service and the
|
|
CLI cannot disagree about what a valid package is — a service accepting
|
|
something the CLI rejects would be exactly the divergence this project exists to
|
|
prevent. Importing it is not changing it; `reference/` stays the
|
|
dependency-light conformance witness.
|
|
|
|
**Test-vs-production difference found and handled.** SQLite autoincrements
|
|
`INTEGER PRIMARY KEY` only, never `BIGINT`, so the SQLite-backed tests could not
|
|
insert a row. `BigInteger().with_variant(Integer, "sqlite")` keeps `BIGINT` on
|
|
PostgreSQL, where this actually runs, while letting the tests exercise the same
|
|
models and the same migration.
|
|
|
|
## Publish API
|
|
|
|
```task
|
|
id: CANP-WP-0006-T04
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "929932b6-931b-5409-a648-b6814f07f0b4"
|
|
```
|
|
|
|
`POST /packages` accepting a package, validating it with the same rules as the
|
|
CLI, and refusing a re-publish of an existing `<id>@<version>` with different
|
|
content (§ 17). Strict packaging applies: reserved paths and manifest-referenced
|
|
files only (§ 2).
|
|
|
|
Namespace policy (§ 20.1) is enforced here rather than advised, because unlike a
|
|
filesystem registry a service *can* authenticate a publisher. Note what identity
|
|
mechanism it uses; if there is none yet, say so and refuse writes rather than
|
|
accepting anonymous publishes into a closed namespace.
|
|
|
|
## HTTP registry in the reference CLI
|
|
|
|
```task
|
|
id: CANP-WP-0006-T05
|
|
status: todo
|
|
priority: medium
|
|
state_hub_task_id: "8dacbb68-aaa2-5f91-942d-a0667f1f1fc7"
|
|
```
|
|
|
|
Teach `--registry` to accept an `https://` URL, so `publish` and `install` work
|
|
against the service. § 20 already allows an HTTP registry; this is the first
|
|
implementation of one, and the first real test of whether package semantics
|
|
survive a transport change unmodified — which is what INTENT principle 10
|
|
claims.
|
|
|
|
If they do not survive it, that is a finding about the format, not a bug to
|
|
paper over in the client.
|
|
|
|
## Image and smoke contract
|
|
|
|
```task
|
|
id: CANP-WP-0006-T06
|
|
status: todo
|
|
priority: medium
|
|
state_hub_task_id: "3c008ebe-bf07-5cee-8678-7b1ed27283ef"
|
|
```
|
|
|
|
Dockerfile and a published image, plus the checks a `rapp` smoke contract will
|
|
assert: health ok, migration at head, private service only, image digest match.
|
|
|
|
Completing this produces the digest that `rapp-canned-prompts` needs to pin, at
|
|
which point that repo can be created against something real.
|