DevRunbook-Public/docs/45-milestone-two-library-explorer.md

45 — Milestone 2 Library Explorer evidence

Scope and evidence identity

Milestone 2 delivers the first authenticated premium end-user experience on top of the Milestone 1 package catalog. The implementation is represented by commits 56e7e6e, a8493a4, bc4d721, c1b10a7, and 3397226.

Authoritative validation used an isolated checkout at commit 3397226 on Unraid 7.2 (linux/amd64) with Docker 27.5.1, Compose 2.40.3, Node.js 24.18.0 and PostgreSQL 17.9. The workstation Node.js 23.7.0 result is supporting feedback only and is not milestone evidence.

Delivered behavior

• Authenticated, workspace-scoped catalog reads for built-in, private and imported playbook sources, without an instance-administrator bypass.
• Search across title, summary, category, tags, intent and compatibility data; typed facets, deterministic relevance/update/title/quality sorting, cursor pagination and match reasons.
• Personal, idempotent favorites with object-level workspace authorization and same-origin mutation protection.
• URL-owned search, facet, sort, view and favorites state with defensive parsing and recoverable warnings for invalid query values.
• Responsive card and dense library views, lifecycle/risk/quality/autonomy badges, filter recovery, and explicit empty, error and degraded states.
• Authenticated playbook detail and exact-version pages covering purpose, outcomes, use and non-use cases, inputs/defaults, modes, autonomy, compatibility, readable condition ASTs, workflow, guardrails, validation, completion, quality, limitations, package inventory, template preview and history.
• Deprecated and draft content remain readable by direct version while being excluded from default recommendations and composition actions.
• A safe version-and-digest-bound handoff to /composer/new; actual guided composition remains owned by Milestone 4 and no package command is executed.
• Semantic global shell, desktop/mobile navigation, workspace and actor presentation, system/light/dark themes, reduced-motion support and a keyboard command palette.

Defects found by live validation

The first production browser run exposed an empty-source SQL defect: the URL layer supplied source: [], which the PostgreSQL predicate interpreted as an empty IN set. effectiveCatalogSources now maps omitted and empty selections to the governed built-in/private/imported scope, with regression tests. The same run exposed repeated login rate limiting in parallel browser workers and nested Server Component authentication errors. Browser authentication now uses one global storage state, and nested pages redirect through a shared authenticated page boundary without logging stack traces.

The API review also found that favorite failures did not conform to the published Error schema. All favorite mutation failures now use the governed error envelope with a UUID request ID; dependency failures are a safe 503, and foreign-origin failures no longer use a different top-level shape. OpenAPI now declares the observed playbook/favorite statuses and canonical repeated array serialization for multi-value filters.

Automated and live evidence

Check	Result	Evidence
python scripts/validate_pack.py	PASS	28 P0 packages, 6 normative examples, 72 catalog entries, 9 schemas and the OpenAPI contract valid.
python scripts/reference_compose.py --check	PASS	28 reference prompts byte-identical.
Database unit gate	PASS	8 files passed, 1 optional integration file skipped; 29 tests passed and 3 integration tests skipped.
Web unit gate	PASS	15 files and 80 tests passed, including URL state, detail projection, shell/theme/palette and API boundaries.
pnpm test:security	PASS	2 files and 11 hostile-input, redaction, origin and dependency-boundary tests passed after moving adapter wiring out of route handlers.
Production image build and startup	PASS	Web, worker and migrate images built at commit 3397226; web, worker and PostgreSQL healthy.
Production API matrix	PASS	Unauthenticated 401; 28-item catalog; facets; empty-source default; combined search/filter; detail; exact-version digest; favorite PUT/filter/DELETE; foreign-origin governed 403.
Playwright production matrix	PASS	23 tests passed in desktop Chromium and 390×844 narrow projects; 3 intentional skips.
Production log scan	PASS	Zero secret/header/token patterns and zero uncaught/authentication stack patterns.
Container boundary inspection	PASS	Web and worker run as node with read-only roots; all declared health checks healthy.

The three browser skips are deliberate: the two setup-recovery cases require an uninitialized database and are already authoritative Milestone 0 evidence; the favorite mutation runs only in desktop Chromium to prevent two parallel projects from racing over the same persisted favorite. The narrow project still verifies every non-mutating critical flow.

Requirement status

Completed for the authenticated runtime catalog:

• FR-LIB-002, FR-LIB-003, FR-LIB-004, FR-LIB-005, FR-LIB-007, FR-LIB-008;
• FR-DET-001 through FR-DET-006.

Partially complete and deliberately not overstated:

• FR-LIB-001: all 28 built-ins are live and the authorization/query boundary supports workspace-private/imported content; private authoring/import UI is still Milestone 7 work.
• FR-LIB-006: personal favorites are persisted and verified; named collections remain open.
• FR-DET-007: an exact version/digest handoff works without a repository profile; the interactive composer is Milestone 4.

Operational notes

The validation environment file is stored outside the Git checkout at mode 0600, and no credentials, cookies or raw tokens are recorded here. The application remains fully usable without a Gitea connection. No migration or new production secret was introduced by Milestone 2.