103 lines
5.8 KiB
Markdown
103 lines
5.8 KiB
Markdown
# 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.
|