# canned-prompts service

The hosted registry and index (`CANP-WP-0006`). Product ownership lives here
alongside the specification and the reference CLI; deployment and operation will
belong to `rapp-canned-prompts` once there is an image digest to pin.

This service **hosts** packages. It does not execute them — `INTENT.md`'s
deliberate boundary holds, so rendering stays deterministic and a `derive`
default remains a declaration the service does not satisfy.

`reference/` is deliberately untouched by this. It is the format's conformance
witness and stays dependency-light; the service is a separate consumer of the
same package semantics.

## Stack

FastAPI, SQLAlchemy, Alembic, PostgreSQL — matching `state-hub` and
`sbom-nexus`.

```bash
cd service
uv venv && uv pip install -e ".[dev]"
.venv/bin/python -m pytest -q

export CANNED_PROMPTS_DATABASE_URL=postgresql+psycopg://...
.venv/bin/alembic upgrade head
.venv/bin/uvicorn canned_prompts_service.api:create_app --factory
```

`CANNED_PROMPTS_DATABASE_URL` has **no default**. A service that silently falls
back to a local database when its real one is misconfigured is worse than one
that refuses to start.

## Health surface

`RailianceAppDeploymentGuide.md` requires unauthenticated `/healthz` and
`/readyz`; `/state/health` matches the rest of the fleet.

| Endpoint | Answers | Fails when |
|---|---|---|
| `/healthz` | is the process up | never — deliberately checks nothing else, so a database blip does not restart pods |
| `/readyz` | can it serve | no database configured, unreachable, or schema not migrated |
| `/state/health` | fleet-shaped status | same as `/readyz`, reported as `degraded` |

Connectivity and schema are checked separately. Both mean not-ready, but they
send an operator to different places — credentials and network, or an unrun
migration — so collapsing them into one message would send people to the wrong
one.

## Tenancy

Every table holding owned data carries a `tenant` key from migration `0001`,
per `business-app-service-contract_v0.1` § 1.3. The service is deployed
single-tenant today; the key is present so a later consolidation is a data copy
rather than a rewrite, and no query may assume it is the only tenant (§ 1.4).

Uniqueness is `(tenant, registry, package_id, version)` — registry-scoped
because identity is (§ 3.2), and tenant-scoped so two tenants may legitimately
hold the same id.

## Schema

| Table | Holds |
|---|---|
| `package_versions` | one immutable `<registry>:<id>@<version>`, its manifest, and indexed discovery fields |
| `package_files` | the package's files as content, not parsed into rows |
| `index_entries` | how a version arrived here (§ 20.3): source, method, `included_at` never overwritten, `last_seen_at` |

## Read API

Routes address packages with the format's own reference syntax
(`<registry>:<id>@<version>`, § 3.2 and § 17) rather than a second one invented
for HTTP. A package id contains `/`, so the reference is captured as a greedy
path and parsed; each route keeps a distinct prefix so the greediness cannot
swallow a neighbouring segment.

| Route | Returns |
|---|---|
| `GET /packages?q=&registry=` | search over id, name, summary and tags |
| `GET /packages/{id}` | the versions of an id |
| `GET /packages/{id}@{version}` | one manifest |
| `GET /archives/{id}@{version}` | the package's files, text or base64 |
| `GET /index` | § 20.3 entries: source, method, `included_at`, `last_seen_at` |

A bare id present in more than one registry returns **409 with the candidates**,
never a guess (§ 3.2). 409 rather than 300 because the request is answerable —
once the caller says which registry they meant.

Asking for a package without naming a version applies § 17.1's selector rules,
so a prerelease is never chosen implicitly.

## Publish API

`POST /packages` takes `{registry, source, files}`, where `files` is the same
shape `GET /archives` returns — so an archive round-trips into a publish
without translation, and a mirror is a GET followed by a POST.

Validation is the reference implementation's, applied to the posted files
materialized in a temporary directory. Only reserved paths and
manifest-referenced files are stored (§ 2); path traversal is refused.
Re-publishing identical content is accepted, different content under the same
`<id>@<version>` is 409 (§ 17).

### What identity means here

A single shared bearer token (`CANNED_PROMPTS_PUBLISH_TOKEN`), proving the
caller is **the operator of this service** — not per-publisher identity. Every
holder of the token is indistinguishable.

With no token configured the service is **read-only**. That is the correct
default rather than an inconvenience: § 20.1 asks a registry to refuse
publication into a closed namespace it does not consider the publisher to own,
and an unauthenticated service considers nobody to own anything.

Namespace claims (§ 20.1) live in `namespace_claims` and are **enforced** here,
which a filesystem registry cannot do at all — but only as precisely as the
identity behind them. A `closed` namespace is protected from anonymous callers;
it cannot be attributed among several publishers. Until per-publisher identity
exists, a claim's `owner` is documentation rather than an access decision, and
the code says so where it matters.

## Status

`CANP-WP-0006` T01–T04 are done: skeleton, health surface, tenant-keyed schema
(migrations `0001`–`0002`), and the read and publish APIs. The HTTP registry
client in the CLI and the container image (T05–T06) are not built yet. T06
produces the image digest that `rapp-canned-prompts` needs to pin.

Per-publisher identity is deferred, and is the main thing standing between this
and a service that several people can publish to.