PUL-F009: URL parameter — composition

[Brad-Edwards]

PUL-F009 | FUNCTIONAL | MUST | Wave 1 | DRAFT

Requirements

• PUL-F009 — URL parameter — composition

Statement

When the composition URL parameter is present, the runtime SHALL resolve the addressed composition manifest and use it as the navigation context.

Rationale

Required for presenting and inspecting scenes within a specific composition.

---

Created from Ground Control requirement PUL-F009

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #18). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #18). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

PUL-F009 implementation plan

PUL-F009 says: "When the composition URL parameter is present, the runtime SHALL resolve the addressed composition manifest and use it as the navigation context."

Coverage assessment

The runtime support for the composition URL parameter landed end-to-end with PUL-F008 (PR #70 / merge 5e0dc52). Tracing the requirement clause-by-clause against the current dev tree:

1. Trigger — "when the composition URL parameter is present": parseNavigationSearch (src/runtime/navigation.ts) recognizes composition, validates it as a kebab-case identifier, and produces kind: 'composition' | 'composition-scene' | 'composition-index' locators. Tests: tests/runtime/navigation.test.ts composition describe block (lines ~110–145), combinations block (~248, ~261, ~277), bootstrap parse-and-dispatch tests (~660). All five accepted shapes are pinned.
2. Resolve the addressed composition manifest: resolveSceneNavigation (src/runtime/scene-navigation.ts) looks up the composition in CompositionRegistry, range-checks indexes, validates membership for composition+scene, rejects ambiguous locators, and snapshots the manifest slice + matching scene modules. Tests: tests/runtime/scene-navigation.test.ts kind: "composition" block (~99: success, missing, empty, broken-references aggregation), kind: "composition-scene" block (~170), kind: "composition-index" block (later in file).
3. Use it as the navigation context: SceneNavigationCompositionContext carries id, manifestSlice, sceneSlice. loadSceneNavigationTarget plays that slice through resolveComposition so the URL-loaded composition inherits the full PUL-F004 lifecycle. The scene-loader (src/runtime/scene-loader.ts) writes data-pulsar-composition-target for any composition target. The browser entry (src/main.ts) wires bootstrapNavigation → pulsar:navigate → loader.handle(), so URL → composition runs at startup and on every popstate (ADR-007 + ADR-013 + ADR-014).

The dispatcher and parser fully cover composition, composition+scene, composition+index. The scene-loader test suite explicitly covers composition+scene end-to-end (scene-loader.test.ts:99) but does not pin the canonical composition-only case or the composition+index case at the loader level.

Scope of this PR

PUL-F009 is implementation-complete on the production side. This PR adds the requirement-anchored regression tests that pin PUL-F009's canonical behavior at the loader boundary, then transitions GC state.

Tests

Add two tests to tests/runtime/scene-loader.test.ts in the existing "happy path — single scene + composition" describe block:

1. loads the composition manifest from index 0 when the locator is kind: "composition" (PUL-F009):

   • Build a 2-scene composition (['intro', 'middle']).
   • loader.handle({ locator: { kind: 'composition', composition: 'full-talk' } }).
   • Assert data-pulsar-scene-target === 'intro' (head of slice).
   • Assert data-pulsar-composition-target === 'full-talk'.
   • Assert no error attribute.
   • Assert lifecycle ran on the head scene (create/cleanup observed via shared log helper).

2. loads the composition slice from the addressed index when the locator is kind: "composition-index" (PUL-F009):

   • Same composition, index 1.
   • Assert data-pulsar-scene-target === 'middle'.
   • Assert data-pulsar-composition-target === 'full-talk'.

Both tests use the existing buildScene, buildStage, noopRunner helpers in tests/runtime/scene-loader.test.ts; no new fixtures.

Code

No production code changes. The dispatcher, loader, and bootstrap already implement every PUL-F009 clause.

Documentation

• CHANGELOG.md — append a ## [Unreleased] / ### Added bullet noting that the PUL-F008 dispatch and loader chain materializes PUL-F009 (URL parameter → composition resolution → manifest as navigation context), and call out the two new loader-level regression tests for the composition-only and composition+index cases.
• ADR-014 — already updated by Step 2.5 preflight to record that PUL-F009 reuses the PUL-F008 dispatch boundary.

No new ADR

ADR-014 already covers PUL-F009 (the preflight pass on this run extended its decision text to make that explicit). No additional ADR.

Ground Control state changes

After CI + reviews are green:

• Step 15 — transition. PUL-F009 DRAFT → ACTIVE via gc_transition_status.

• Step 16 — traceability reconciliation. Add IMPLEMENTS links from PUL-F009 to:

  • src/runtime/navigation.ts (parser handling composition param)
  • src/runtime/scene-navigation.ts (composition resolution dispatcher)
  • src/runtime/scene-loader.ts (stage attribute + lifecycle wiring)
  • src/main.ts (browser bootstrap)
  • src/runtime/composition-registry.ts (composition addressability)

  Add TESTS links from PUL-F009 to:

  • tests/runtime/navigation.test.ts
  • tests/runtime/scene-navigation.test.ts
  • tests/runtime/scene-loader.test.ts

  Add GITHUB_ISSUE link IMPLEMENTS from PUL-F009 → issue 18 (Mode A — diff materially implements via the new regression tests + the existing PUL-F008 chain).

  Existing DOCUMENTS link to ADR-007 stays.

Cross-cutting concerns reused

• Test fixtures: existing buildScene / buildStage / noopRunner helpers in tests/runtime/scene-loader.test.ts. No new helpers.
• Registry / parser / dispatcher / loader code paths: unchanged.

Risks / non-goals

• Non-goal: changing parser, dispatcher, or loader behavior. Existing tests must stay green; the new tests assert the existing behavior, not a new one.
• Non-goal: modifying PUL-F008's tests. The two new tests are PUL-F009-anchored and named accordingly.
• Risk: the new tests might overlap with existing coverage and feel redundant. Mitigation: name them after PUL-F009 and assert the canonical statement (composition param ⇒ composition manifest as navigation context) so the regression intent is explicit.

Completion gate

pnpm lint && pnpm typecheck && pnpm test (per .ground-control.yaml) plus pre-commit, then push, PR, CI, SonarCloud, codex review (post-push), test-quality review, and the GC reconciliation steps above.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 2 complete for issue #18 on branch '18-pul-f009-url-parameter-composition'. Posted by the MCP server to enforce the pre-push hard-cap-2 contract (issue #796). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

[Brad-Edwards]

Pre-push codex review (uncommitted) — cycle 1 decisions

Two findings from cycle 1, both decision: fix:

1. tests/runtime/scene-loader.test.ts:161 (composition-only test) — only logged intro's lifecycle; middle had no-op hooks, so a regression collapsing ?composition=full-talk into a single-scene intro load would have passed. Fixed: 3-entry manifest (intro, middle, outro), every entry instrumented, log asserts the full create→cleanup pair for all three in manifest order.

2. tests/runtime/scene-loader.test.ts:176 (composition-index test) — used a 2-entry manifest with index=1, so the slice was [middle] — indistinguishable from a single-scene load. Fixed: same 3-entry manifest, index=1 now produces a 2-entry slice (middle, outro); log asserts both run in manifest order.

Re-running pre-push codex review now.

[Brad-Edwards]

gc_codex_review pre-push cycle 2 of 2 complete for issue #18 on branch '18-pul-f009-url-parameter-composition'. Posted by the MCP server to enforce the pre-push hard-cap-2 contract (issue #796). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

[Brad-Edwards]

Pre-push codex review — cycle 2 clean

Cycle 2 returned 0 findings (core + security). The cycle-1 weaknesses (assertions that didn't distinguish a manifest-slice play from a single-scene load) are now fixed: both PUL-F009 loader tests use a 3-entry manifest and assert every entry's create→cleanup runs in manifest order.

The cycle-2 reviewer noted residual informational risk that this PR does not add negative-path coverage for unknown composition ids / out-of-range indexes; codex explicitly classified it as non-blocking. PUL-F009's scope is the happy path ("when composition is present, resolve and use as navigation context"). Negative paths are already covered at the dispatcher level (tests/runtime/scene-navigation.test.ts:99-167), so this is decision: not-applicable for PUL-F009 — no action.

Proceeding to commit + push.

[Brad-Edwards]

Final summary — PUL-F009 ready for review

Issue: #18 — PUL-F009: URL parameter — composition
PR: #72
Plan: issuecomment-4374726948

In-scope requirements

• PUL-F009 — URL parameter — composition — transitioned DRAFT → ACTIVE.

Files changed in this PR

File	Change
tests/runtime/scene-loader.test.ts	added two PUL-F009 regression anchors (composition-only and composition-index canonical cases)
CHANGELOG.md	[Unreleased] / Added entry for the new anchors
docs/adrs/014-url-scene-target-selection.md	preflight extended ADR-014 to make PUL-F009's reuse of the PUL-F008 dispatch boundary explicit

No production-code changes. PUL-F009's parser, dispatcher, loader, and bootstrap chain shipped end-to-end with PUL-F008 (PR #70 / merge 5e0dc52); this PR pins PUL-F009's canonical statement at the loader boundary.

Traceability reconciliation

Added on PUL-F009:

• 5 IMPLEMENTS CODE_FILE links: src/runtime/navigation.ts, src/runtime/scene-navigation.ts, src/runtime/scene-loader.ts, src/runtime/composition-registry.ts, src/main.ts
• 3 TESTS TEST links: tests/runtime/navigation.test.ts, tests/runtime/scene-navigation.test.ts, tests/runtime/scene-loader.test.ts
• 1 IMPLEMENTS GITHUB_ISSUE link → issue PUL-F009: URL parameter — composition #18
• Existing DOCUMENTS ADR-007 link preserved.

Reviews and gates

• Pre-push codex review (uncommitted) — cycle 1: 2 findings (assertion-strength: tests didn't distinguish manifest-slice play from single-scene load), both fixed by switching to a 3-entry manifest with full lifecycle log assertions. Cycle 2: 0 findings. Decisions: issuecomment-4374745947, issuecomment-4374750727.
• CI — green (run 25345632566).
• SonarCloud — quality gate OK; 0 open issues, 0 hotspots for PR PUL-F009: pin composition URL parameter as navigation context #72.
• Post-push codex review — cycle 1: 0 findings.
• Test quality review — 0 issues found.
• Completion gate (pnpm lint && pnpm typecheck && pnpm test) — clean; 508 tests pass (was 506; +2 PUL-F009 anchors).

PR #72 is ready for user review and merge.