PR_26180_OWNER_009-move-api-application

api/API_RUNTIME_BOUNDARY.md

@@ -0,0 +1,16 @@
+# API Runtime Boundary
+
+`api/` contains server/API application runtime implementation for the browser-visible Local API, seeded product data, provider stubs, storage adapters, database adapters, and support services used by repository validation.
+
+It is intentionally not `dev/tests/dev-runtime`:
+
+- `api/` serves runtime behavior that browser pages and local API routes can exercise through the API/service contract during development and targeted validation.
+- `dev/tests/dev-runtime` contains test files that validate that behavior.
+- Moving the implementation into `dev/tests/dev-runtime` would make development pages depend on test-only code and would blur the Browser -> Server API -> Data Source boundary.
+
+Deployment boundary:
+
+- DEV validation may execute `api/` through local server commands.
+- Browser pages, Theme V2 scripts, toolbox pages, and `src/engine` runtime code must use declared API/service contracts instead of importing `api/` directly.
+- If a dev-only adapter is needed by a browser page, expose it through the Local API contract while keeping the implementation under `api/`.
+- Developer-only local bootstrap/orchestration remains outside `api/` until the scoped `dev/local-runtime/` migration PR.

api/guest-seeds/tool-metadata-inventory.js

@@ -0,0 +1 @@
+export * from "../../src/shared/toolbox/tool-metadata-inventory.js";

src/dev-runtime/server/local-api-router.mjs → api/server/local-api-router.mjs

@@ -133,7 +133,7 @@ import {
 import {
   getAdminNavigationItems,
   getOwnerNavigationItems,
-} from "../../api/admin-owner-navigation.js";
+} from "../../src/api/admin-owner-navigation.js";
 import { createPaletteSourceMockDbRows } from "../guest-seeds/palette-source-mock-db.js";
 import {
   SUPABASE_AUTH_PROVIDER_ID,

src/dev-runtime/server/local-api-server.mjs → api/server/local-api-server.mjs

@@ -9,7 +9,7 @@ import { resolveStaticRouteTarget } from "./static-web-root.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const repoRoot = path.resolve(__dirname, "..", "..", "..");
+const repoRoot = path.resolve(__dirname, "..", "..");
 
 function contentTypeForPath(filePath) {
   const extension = path.extname(filePath).toLowerCase();

dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md

@@ -117,7 +117,7 @@ Rules:
 
 ## Current Version/Date
 
-- Project Instructions Version: 2026.06.28.008
+- Project Instructions Version: 2026.06.28.009
 - Date: 2026-06-28
 - Owner: OWNER
 

dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md

@@ -1,6 +1,6 @@
 # Project Instructions Version
 
-Current Project Instructions Version: 2026.06.28.008
+Current Project Instructions Version: 2026.06.28.009
 
 Last Updated: 2026-06-28
 
@@ -16,6 +16,7 @@ Last Updated: 2026-06-28
 - Added `www/` migration map for safe browser-served application movement planning.
 - Added local route-root compatibility toggle documentation for future `www/` activation.
 - Moved browser-served application files under `www/` and made local static serving prefer `www/` by default.
+- Moved server/API application runtime under `api/`; browser API clients remain outside `api/` and developer-only bootstrap remains in `dev/` until the local-runtime migration PR.
 - Codex must read this version file and the latest repository copy of `PROJECT_INSTRUCTIONS.md` before performing work.
 - Codex must discard previously remembered Project Instructions and treat the repository copy as authoritative.
 - Codex must validate canonical report and ZIP paths, branching model, and legacy path avoidance before work proceeds.

dev/build/ProjectInstructions/PROJECT_STATE.md

@@ -1,7 +1,7 @@
 # Project State
 
 ```yaml
-project_state_version: "2026.06.28.008"
+project_state_version: "2026.06.28.009"
 last_updated: "2026-06-28"
 current_main_commit: "40de767476d70cadfd1292c916844c2f31b6f185"
 repository_status:
@@ -10,18 +10,18 @@ repository_status:
   runtime_database: "Postgres"
   creator_metadata: "API to Postgres"
   creator_assets: "API to R2"
-project_instructions_version: "2026.06.28.008"
-repository_structure_version: "2026.06.28.008"
-canonical_layout_version: "2026.06.28.008"
+project_instructions_version: "2026.06.28.009"
+repository_structure_version: "2026.06.28.009"
+canonical_layout_version: "2026.06.28.009"
 active_teams:
   - "Owner"
   - "Alfa"
   - "Bravo"
   - "Charlie"
   - "Delta"
   - "Golf"
-latest_owner_pr: "PR_26180_OWNER_008-move-www-application"
-latest_structure_pr: "PR_26180_OWNER_008-move-www-application"
+latest_owner_pr: "PR_26180_OWNER_009-move-api-application"
+latest_structure_pr: "PR_26180_OWNER_009-move-api-application"
 valid_top_level_folders:
   - "api/"
   - "deploy/"
@@ -40,6 +40,7 @@ valid_dev_folders:
   - "dev/tools/"
   - "dev/workspace/"
 known_technical_debt:
-  - "Legacy transition src buckets remain until scoped migration PRs move them into src/web/, src/api-runtime/, or src/runtime/."
+  - "Browser API client modules remain under src/api/ until the final src layer migration moves them into src/web/ or src/runtime/."
+  - "src/dev-runtime/admin/ remains as a legacy Admin Notes browser-viewer compatibility path until a scoped browser admin migration retires it."
   - "repository_directory_standard.md and codex_project_instructions_startup.md are superseded pointers retained for compatibility."
 ```

dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md

@@ -39,9 +39,9 @@ The backlog is the authoritative source for determining the next logical PRs.
 - Team: Owner
 - Product Area: Repository Architecture Simplification
 - Status: Active
-- Percent Complete: 30%
-- Active PR: PR_26180_OWNER_008-move-www-application
-- Next Milestone: Move server/API application files into `api/`
+- Percent Complete: 40%
+- Active PR: PR_26180_OWNER_009-move-api-application
+- Next Milestone: Move developer-only local runtime into `dev/local-runtime/`
 - Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`; `dev/build/ProjectInstructions/repository/www_migration_map.md`
 
 ## Game Journey MVP

dev/build/ProjectInstructions/repository/canonical_repository_structure.md

@@ -15,7 +15,7 @@ Valid top-level folders:
 
 Root product and repo sections:
 - www/ owns browser-served production website sections, Creator toolbox pages, public game discovery, production Docs & Help, and browser assets.
-- api/ is the target Node/API/server application surface for the repository layout simplification workstream.
+- api/ is the Node/API/server application surface for server entry points, API routing, API services, database access, storage access, auth, setup, publishing, and admin server logic.
 - deploy/ contains deployment configuration.
 - dev/ contains the development workspace.
 - src/ contains deployable application/runtime/API source.
@@ -30,7 +30,9 @@ Final src layer ownership:
 - src/web/ owns browser-facing deployable application modules used by public pages, account/admin surfaces, and Creator tools.
 - src/api-runtime/ owns deployable API/runtime service modules that back the shared Browser -> API -> Postgres/R2 contract.
 - src/runtime/ owns deployable game, tool, engine, and shared runtime capabilities.
-- Existing top-level src/advanced/, src/api/, src/dev-runtime/, src/engine/, src/shared/, and src/tools/ directories are legacy transition buckets until explicit migration PRs move them.
+- Existing top-level src/advanced/, src/api/, src/engine/, src/shared/, and src/tools/ directories are legacy transition buckets until explicit migration PRs move them.
+- Browser API clients remain outside `api/`; browser-served code must use API/service contracts instead of importing top-level `api/` files directly.
+- `src/dev-runtime/admin/` remains only as a legacy Admin Notes browser-viewer compatibility path until a scoped browser admin migration retires it.
 - Do not add new top-level src/ layer names outside src/web/, src/api-runtime/, or src/runtime/ without OWNER approval.
 - Do not use team names in runtime source filenames.
 
@@ -75,18 +77,19 @@ Shared JavaScript:
 Legacy transition buckets:
 - src/advanced/
 - src/api/
-- src/dev-runtime/
 - src/engine/
 - src/shared/
 - src/tools/
+- src/dev-runtime/admin/
 
 These legacy transition buckets may remain until explicit migration PRs move them into `src/web/`, `src/api-runtime/`, or `src/runtime/`.
 
 ## Rules
 
 - Root is standard repository configuration and top-level application shells only.
 - www/ is the browser-served application surface.
-- api/ is the Node/API/server application target surface for migration.
+- api/ is the Node/API/server application surface.
+- Browser-served code must not import top-level `api/` files directly.
 - src/ is deployable application/runtime/API code.
 - dev/ is development workspace only.
 - deploy/ is deployment configuration.

dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md

@@ -1,6 +1,6 @@
 # Repository Layout Architecture Plan
 
-Status: Active Scaffold
+Status: Active Migration
 Owner: Owner
 Scope: Documentation/governance only
 
@@ -22,6 +22,12 @@ This plan does not authorize moving files, changing runtime behavior, changing p
 
 No browser, API, server, test, script, or runtime files move in the scaffold or migration-map PRs.
 
+`PR_26180_OWNER_007-www-route-root-compatibility` prepared configurable web-root serving without moving browser files.
+
+`PR_26180_OWNER_008-move-www-application` moved browser-served application files under `www/` and made local static serving prefer `www/` while preserving public URLs.
+
+`PR_26180_OWNER_009-move-api-application` moves server/API application runtime under `api/` while preserving `/api/*` route behavior. Browser API client modules remain outside `api/`, and developer-only local startup orchestration remains under `dev/` until the local-runtime migration PR.
+
 ## Proposed Future Layout
 
 ```text

dev/build/ProjectInstructions/repository/www_migration_map.md

@@ -107,19 +107,19 @@ These references can be preserved temporarily by serving compatibility paths fro
 
 ## Current Local Web Server Root Behavior
 
-Three active server/helper surfaces currently resolve static browser paths from the repository root:
+Three active server/helper surfaces currently resolve static browser paths through the shared static route resolver:
 
 | File | Current behavior |
 | --- | --- |
-| `dev/scripts/start-dev.mjs` | Team-aware bootstrap static server resolves requests with `path.resolve(repoRoot, \`.\${normalizedPath}\`)`. `/` maps to `/index.html`; `/tools/*` maps to `/toolbox/*`; `/admin/admin-notes.html` maps to `/src/dev-runtime/admin/notes.html`. |
-| `src/dev-runtime/server/local-api-server.mjs` | Legacy local API alias serves API routes and falls back to static files from `repoRoot`. `/tools/*` maps to `/toolbox/*`; `/admin/admin-notes.html` maps to `/src/dev-runtime/admin/notes.html`. |
-| `dev/tests/helpers/playwrightRepoServer.mjs` | Playwright test server mirrors repo-root static serving and the `/tools/*` and admin-notes compatibility routes. |
+| `dev/scripts/start-dev.mjs` | Team-aware bootstrap static server resolves requests with `resolveStaticRouteTarget()`, preferring `www/` while preserving public route URLs and compatibility routes. |
+| `api/server/local-api-server.mjs` | Legacy local API alias serves API routes and falls back to `resolveStaticRouteTarget()`, preferring `www/` while preserving public route URLs and compatibility routes. |
+| `dev/tests/helpers/playwrightRepoServer.mjs` | Playwright test server mirrors the shared static route resolver and compatibility routes. |
 
-The actual `www/` move must update these filesystem lookup roots or introduce a shared route resolver that can resolve public routes to `www/` while preserving API route ownership.
+The actual `www/` move introduced the shared route resolver so public URLs continue to resolve while filesystem ownership lives under `www/`.
 
 ## Current Test Assumptions
 
-Playwright and runtime tests currently assume root-based public routes and root-relative filesystem paths:
+At the time of the migration map, Playwright and runtime tests assumed root-based public routes and root-relative filesystem paths:
 
 - 96 Playwright/helper/runtime files reference public routes such as `/toolbox`, `/account`, `/admin`, `/games`, `/learn`, `/legal`, `/marketplace`, `/memberships`, or `/index.html`.
 - `dev/tests/playwright/tools/ToolNavigationPrevNext.spec.mjs` opens `/toolbox/index.html` and `/toolbox/game-design/index.html`.
@@ -128,7 +128,7 @@ Playwright and runtime tests currently assume root-based public routes and root-
 - `dev/tests/runtime/V2*` tests frequently assert `toolbox/{tool}/index.html` filesystem or URL behavior.
 - `dev/scripts/run-node-tests.mjs` and `dev/scripts/run-node-test-files.mjs` register root aliases for `/src/` and `/toolbox/`.
 
-The move PR must update test helpers and route expectations in the same PR that changes the filesystem root. Browser-visible URLs should remain stable unless Owner explicitly approves a public URL change.
+The `www/` move PR updated test helpers and route expectations for the filesystem root change. Browser-visible URLs must remain stable unless Owner explicitly approves a public URL change.
 
 ## Preserve Versus Rewrite
 
@@ -151,7 +151,6 @@ The move PR must update test helpers and route expectations in the same PR that
 
 ### Defer
 
-- Moving server/API code into `api/`.
 - Moving developer bootstrap into `dev/local-runtime/`.
 - Removing legacy root compatibility routes.
 - Changing package commands.

dev/build/database/runbook.md

@@ -170,8 +170,8 @@ are stable. It may show validation, apply, backup, restore, and migration
 history status, but it must not execute database operations from the browser.
 
 The status surface currently routes through
-`src/dev-runtime/server/local-api-router.mjs`. That filename is retained as a
-legacy runtime filename for now; do not infer local database behavior from it.
+`api/server/local-api-router.mjs`. That local API filename is retained for now;
+do not infer local database behavior from it.
 
 ## Rollback Guidance
 

dev/reports/PR_26180_OWNER_009-move-api-application_branch-validation.md

@@ -0,0 +1,23 @@
+# PR_26180_OWNER_009 Branch Validation
+
+## Startup Validation
+
+- Project Instructions version: 2026.06.28.009
+- Repository source: PASS
+- Cached memory discarded: PASS
+- Canonical paths loaded: PASS
+- `PROJECT_BRANCHING_POLICY.md` loaded: PASS
+
+## Branch
+
+- Current branch: `PR_26180_OWNER_009-move-api-application`
+- Expected stacked base: `PR_26180_OWNER_008-move-www-application`
+- Base ancestry check: PASS
+- Worktree before build: clean on stacked base before branch creation
+
+## Scope Validation
+
+- Server/API runtime moved into `api/`: PASS
+- Dev-only bootstrap/orchestration not moved: PASS
+- Browser/www direct imports of top-level `api/` implementation avoided: PASS
+- Runtime/UI product behavior changes avoided: PASS

dev/reports/PR_26180_OWNER_009-move-api-application_manual-validation-notes.md

@@ -0,0 +1,14 @@
+# PR_26180_OWNER_009 Manual Validation Notes
+
+## Manual Review
+
+- Confirmed `src/dev-runtime/` now contains only the Admin Notes browser-viewer compatibility files.
+- Confirmed top-level `api/` contains server/API runtime ownership folders.
+- Confirmed browser-facing imports use `src/api` client modules rather than top-level `api/` implementation modules.
+- Confirmed developer bootstrap files remain under `dev/scripts/` for the later local-runtime migration PR.
+- Confirmed active Project Instructions and backlog now describe this API migration step.
+
+## Manual Route Notes
+
+- Representative `/api/*` endpoints were exercised through the moved local API server.
+- Public URL preservation was checked through the targeted Browser API URL Playwright smoke.

dev/reports/PR_26180_OWNER_009-move-api-application_report.md

@@ -0,0 +1,29 @@
+# PR_26180_OWNER_009-move-api-application Report
+
+## Executive Summary
+
+PASS. This PR moves server/API application runtime from `src/dev-runtime/` into top-level `api/` while preserving public `/api/*` route behavior.
+
+The move keeps developer-only local bootstrap/orchestration in `dev/` for the later local-runtime PR. Browser-facing API client modules remain in `src/api/`; `www/` does not import top-level `api/` implementation files directly.
+
+## Scope Completed
+
+- Moved Local API server runtime, router, route helpers, services, persistence, database, storage, auth, seed, guest seed, marketplace, membership, legal, messages, project package, team, testing, and toolbox API server modules under `api/`.
+- Renamed `src/dev-runtime/DEV_RUNTIME_BOUNDARY.md` to `api/API_RUNTIME_BOUNDARY.md` and updated boundary language.
+- Left `src/dev-runtime/admin/` in place as the documented legacy Admin Notes browser-viewer compatibility path.
+- Updated dev scripts, targeted tests, Playwright helpers, and active governance docs to reference `api/`.
+- Updated Project Instructions version to `2026.06.28.009`.
+- Updated `BACKLOG_MASTER.md` to show Repository Architecture Simplification at 40% with next milestone `dev/local-runtime/`.
+
+## Public Behavior
+
+- `/api/*` route behavior is preserved.
+- Public browser URLs are preserved.
+- No product feature behavior was intentionally changed.
+- No API endpoint rename was introduced.
+- Browser code continues to use API/service contracts through client modules, not direct server implementation imports.
+
+## Notes
+
+- The first route smoke attempt included `/api/session/users`, which returned 503 because that route depends on configured provider/session-user data. The final smoke used provider-independent API routes and passed.
+- Targeted Playwright initially exposed a stale test-local static server assumption from the prior `www/` move. The spec now uses the shared static route resolver, preserving public routes while serving from `www/`.

dev/reports/PR_26180_OWNER_009-move-api-application_requirement-checklist.md

@@ -0,0 +1,13 @@
+# PR_26180_OWNER_009 Requirement Checklist
+
+| Requirement | Status | Evidence |
+| --- | --- | --- |
+| Base on `PR_26180_OWNER_008-move-www-application` | PASS | Branch ancestry check passed. |
+| Move server/API runtime files into `api/` | PASS | Server/router/services/persistence/storage/auth/seed modules moved under `api/`. |
+| Preserve `/api/*` route behavior | PASS | Route smoke passed for representative `/api/*` endpoints. |
+| Do not move dev-only local runtime/bootstrap orchestration yet | PASS | Bootstrap and startup orchestration remain in `dev/scripts/`. |
+| Do not move tests except path/import updates | PASS | Test changes update imports and static route helper assumptions only. |
+| Do not change product behavior | PASS | No intentional endpoint or public URL behavior change. |
+| Browser/www must not import `api/` files directly | PASS | Browser code continues importing `src/api` client modules; boundary test passes. |
+| Update reports under canonical path | PASS | Reports generated under `dev/reports/`. |
+| Produce repo-structured ZIP under canonical path | PASS | ZIP generated under `dev/workspace/zips/`. |

dev/reports/PR_26180_OWNER_009-move-api-application_validation-report.md

@@ -0,0 +1,26 @@
+# PR_26180_OWNER_009 Validation Report
+
+## Validation Commands
+
+| Command | Result |
+| --- | --- |
+| `git diff --check` | PASS |
+| `npm run validate:canonical-structure` | PASS |
+| `node --check` for changed JS/MJS files | PASS, 86 changed JS/MJS files |
+| `node ./dev/scripts/run-node-test-files.mjs dev/tests/dev-runtime/StaticWebRootCompatibility.test.mjs dev/tests/dev-runtime/LocalApiStartupLogging.test.mjs dev/tests/dev-runtime/PublicEnvironmentConfig.test.mjs dev/tests/dev-runtime/DevRuntimeBoundary.test.mjs dev/tests/dev-runtime/AdminNotesBoundary.test.mjs dev/tests/dev-runtime/ArchitectureCleanupApiNavInvitations.test.mjs dev/tests/api/admin-system-health/contract.test.mjs` | PASS, 7/7 files and 30/30 subtests |
+| Inline `/api/*` route smoke using `startLocalApiServer()` | PASS |
+| `npx playwright test dev/tests/playwright/tools/BrowserApiUrlConfig.spec.mjs --reporter=line` | PASS, 1/1 |
+
+## Route Smoke Endpoints
+
+- `/api/runtime/health` - PASS
+- `/api/public/config` - PASS
+- `/api/session/current` - PASS
+- `/api/session/modes` - PASS
+- `/api/guest/seed` - PASS
+- `/api/providers/contract` - PASS
+
+## Notes
+
+- `/api/session/users` was not used in the final smoke because it depends on configured provider/session-user data and returned 503 in this local environment.
+- Playwright is targeted because API route behavior and browser API URL handling are adjacent to this move.