# 44 — Milestone 1 package-ingestion evidence

## Outcome

Milestone 1 passed on 2026-07-27 at commit
`b7dcb5d041f78027c9b6d3edf1d630098337befd`. The authoritative host was the
Unraid 7.2 `linux/amd64` server with Docker 27.5.1, Compose 2.40.3, the pinned
Node.js 24.18.0 image and PostgreSQL 17.9. The Windows Node.js 23 runtime was
not used as milestone evidence.

This milestone closes the canonical built-in content model and persistence
contracts. It does not claim the Library Explorer UI, private ZIP import,
Prompt Lab or package export; those remain assigned to later milestones.

## Content validation and catalog governance

The runtime loader validates package schemas, normalized UTF-8 content,
declared inventory, non-executable regular files, condition and template
semantics, lifecycle evidence and deterministic digests. Failures use
structured `{ path, code, message, remediation }` issues. A catalog load
aggregates errors across package directories rather than hiding later failures.

The separate seed-catalog loader validates all 72 roadmap entries and
cross-checks the 28 publishable P0 entries against runtime package identity,
title, category, type, risk tier, default mode and default autonomy. P1/P2
entries are never materialized as executable runtime packages.

Unit evidence includes malformed YAML, schema failure, semantic secret
exposure, unknown template variables, executable files, invalid UTF-8,
hardlinks, multi-package aggregation, catalog mismatch and duplicate identity.
The governed Python validator independently confirmed 28 P0 packages, six
normative examples, 72 catalog entries, nine schemas and 28 golden prompts.

## Import, storage and query contracts

The application layer owns an importer contract independent of web and worker
frameworks. The PostgreSQL adapter uses an advisory lock and one transaction to
create playbook identities and immutable semantic versions. Identical imports
are no-ops; a reused semantic version with another digest is rejected with
`playbook_version_conflict`. A database trigger independently prevents updates
to published `playbook_versions` rows.

The worker validates and cross-checks all built-ins before polling, imports
them through the shared adapter, and logs counts only. Both supported layouts
are covered: production `/content/{playbooks,catalog}` and development
`/app/content/playbooks` plus `/app/catalog`.

The PostgreSQL catalog chooses the highest eligible semantic version, including
correct numeric and prerelease ordering, and excludes draft or deprecated
versions from the current recommendation. Search uses the indexed search
projection and typed category, risk, lifecycle and source filters. Detail
queries return the current package plus complete version history; exact-version
queries return the immutable manifest, template and quality evidence.

The HTTP boundary exposes:

- `GET /api/v1/playbooks` with `{ items, nextCursor, facets }`;
- validated `q`, `category`, `riskTier`, `lifecycle` and `source` parameters;
- `GET /api/v1/playbooks/{slug}` for current detail and history;
- `GET /api/v1/playbooks/{slug}/versions/{version}` for exact content;
- stable `422` responses for invalid query values.

A public ZIP validation/import endpoint is intentionally not invented here.
The normative API assigns operator package import to the Prompt Lab milestone;
M1's invalid-input acceptance is proved at the canonical content boundary.

## Authoritative validation

The clean Git-bundle clone contained only committed files. The development
target performed a frozen pnpm 10.33.0 install under Node.js 24.18.0. Commands
and results:

| Command or check | Result |
| --- | --- |
| `pnpm verify` | PASS: formatting; 13 lint, typecheck and build workspaces; all unit tests; pack validation; reference composition. |
| `pnpm test:security` | PASS: 2 files, 11 tests. |
| `python3 scripts/validate_pack.py` through `pnpm verify` | PASS: 28 P0, 6 examples, 72 catalog entries, 9 schemas and 28 golden fixtures. |
| `python3 scripts/reference_compose.py --check` through `pnpm verify` | PASS: 28 byte-identical prompts. |
| `pnpm db:migrate` on an empty PostgreSQL 17 volume | PASS; replay after tests also exited zero. |
| `pnpm test:integration` with explicit database and artifact targets | PASS: 3 files, 7 tests. |
| Production `docker compose build` | PASS for web, worker and migrate; image digests recorded by Docker. |
| Production `docker compose up -d --wait` | PASS: PostgreSQL, web and worker healthy; migration exited successfully. |

An initial operator test invocation omitted the required temporary
`ARTIFACT_ROOT`; that invocation was rejected explicitly. Its named temporary
database and artifact volumes were removed, recreated empty and then used for
the passing migration and integration run above.

## Live production evidence

On the fresh Compose database, the worker reported 28 inserted playbooks and 28
inserted versions. After a controlled worker restart it reported zero inserts
and 28 unchanged versions and returned healthy. Direct PostgreSQL counts were
28 playbooks and 28 versions.

Live API checks returned 28 list items. The combined query `root cause` plus
`bugfixing`, `moderate`, `reviewed` and `built_in` returned only
`root-cause-bugfix`. Its detail response exposed current version `1.0.0` and one
history item. The exact-version response contained the manifest, 591-byte
template and quality record. An invalid risk tier returned `422`.

The PostgreSQL integration test attempted to mutate a published version and
observed the immutable trigger rejection. It also proved identical re-import,
digest-conflict rejection, indexed search, full detail and exact-version reads.

Web and worker ran as user `node` with read-only root filesystems and remained
healthy. A production log scan found none of the configured secret values and
no `Authorization:` or `Bearer ` markers.

## Browser evidence

The in-app Chromium browser exercised the live Unraid deployment:

- the home catalog rendered persisted built-ins without Gitea;
- the Root-Cause Bug Fix detail rendered identity, lifecycle, risk, version and
  digest and stated the non-execution boundary;
- at 390 by 844 CSS pixels the detail article remained visible and document
  width did not exceed viewport width;
- browser warnings and errors: zero.

Search controls, URL-preserved filters, favorites, dense view, enriched package
detail and their keyboard/accessibility gates remain Milestone 2 scope.

## Milestone decision

All Milestone 1 acceptance bullets in `IMPLEMENTATION_PLAN.md` have actual unit,
PostgreSQL, production-container and browser evidence. No project-wide release
artifact or final handoff is created at this intermediate gate. Milestone 2 may
begin.