PUL-F008: URL parameter — scene

[Brad-Edwards]

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

Requirements

• PUL-F008 — URL parameter — scene

Statement

When the scene URL parameter is present, the runtime SHALL load the addressed scene as the navigation target.

Rationale

Direct scene addressing is the basis of agent verification and reviewer use.

---

Created from Ground Control requirement PUL-F008

[Brad-Edwards]

/implement plan (2026-05-03T00:00:00Z)

Context

PUL-F008 requires: "When the scene URL parameter is present, the runtime
SHALL load the addressed scene as the navigation target."

ADR-013 (added during preflight) constrains the implementation:

• Parse scene once from URLSearchParams at the runtime boundary.
• Validate identifier shape via the shared isKebabIdentifier rule from
  src/runtime/identifier.ts; do not add a URL-only regex.
• Resolve existence through SceneRegistry.has / SceneRegistry.get;
  no array scans, no dynamic imports, no if/else dispatch.
• Treat malformed or unknown scene ids as navigation errors before
  any scene lifecycle hook runs.
• Preserve the existing lifecycle contract: preload → create(ctx) →
  timeline → cleanup(ctx).
• URL state is authoritative; no localStorage / cookie fallback.
• scene is orthogonal to mode.
• If composition is also present, scene targets a scene within that
  composition (composition handling is future work — out of scope here).
• Positional index must not become identity when scene is supplied.
• Handle repeated / conflicting scene parameters explicitly because
  URLSearchParams.get() silently picks one value.

Approach

1. src/runtime/url-navigation.ts (new) — owns the scene URL
   parameter contract.

   • SceneNavigationTarget interface: { scene: SceneModule } — the
     navigation target shape. Future URL parameters (composition, beat,
     mode) extend this graph; PUL-F008 owns the scene-only target.
   • resolveSceneNavigationTarget(input, registry) — pure parser. Accepts
     URL | URLSearchParams | string. Algorithm:
     1. Normalize input to a URLSearchParams.
     2. getAll('scene') to surface repetition. If length > 1, throw.
     3. If length === 0, return null (scene param absent — caller
        decides whether to fall through to other URL routing).
     4. Validate the single value with isKebabIdentifier; throw on
        malformed shape.
     5. Call registry.has(id); throw on miss.
     6. Return { scene: registry.get(id) }.
   • All thrown errors carry the scene navigation failed: prefix so
     callers can pattern-match origin (mirrors composition resolution failed: grammar from composition-resolver.ts).
   • The function does not call any lifecycle hook. All errors fire
     before preload / create / timeline / cleanup can run.
   • loadSceneNavigationTarget(target, options) — thin lifecycle bridge
     that builds a single-entry composition manifest from
     target.scene.id and delegates to resolveComposition. This
     satisfies the ADR-013 clause that scene URL loading must go through
     the existing runtime lifecycle (preload → create → timeline →
     cleanup) without inventing a parallel single-scene runner.

2. tests/runtime/url-navigation.test.ts (new) — TDD spec covering:

   • Happy path: scene present + valid kebab id + in registry → returns
     target whose .scene is the registry module.
   • Scene absent: empty URLSearchParams, empty URL, URL with other
     unrelated params → returns null.
   • Repeated scene: ?scene=a&scene=b and ?scene=a&scene=a → throws
     (the ADR-013 explicit handling clause).
   • Malformed shape: empty string, uppercase, underscore,
     leading/trailing hyphen, consecutive hyphens, whitespace, non-ASCII,
     numeric-only-with-bad-chars → throws.
   • Valid shape but not in registry → throws.
   • Input shape coverage: URL object, URLSearchParams, string
     (search string and full URL).
   • Lifecycle invariants: errors throw before any registry get / scene
     hook is invoked. Verified by passing a registry whose only scene's
     create would record a call; assert no call recorded on failure.
   • Orthogonality: presence of mode, composition, index, beat
     parameters does not change scene resolution. (This documents the
     scope boundary — those parameters are owned by future requirements.)
   • End-to-end via loadSceneNavigationTarget + the existing
     resolveComposition: preload → create → timeline → cleanup recorded
     in order for the addressed scene; preload throwing aborts before
     create; create throwing still calls cleanup (preserves
     mandatory-cleanup invariant).

3. CHANGELOG.md — [Unreleased] → ### Added entry listing the
   new module, test file, and PUL-F008 reference.

4. docs/adrs/013-url-scene-target-selection.md,
   docs/adrs/README.md — already added by codex preflight; no
   further changes here.

Critical files

• New: src/runtime/url-navigation.ts
• New: tests/runtime/url-navigation.test.ts
• Modified: CHANGELOG.md
• Pre-existing from preflight: docs/adrs/013-url-scene-target-selection.md,
  docs/adrs/README.md

Reused existing patterns / helpers

• isKebabIdentifier (src/runtime/identifier.ts:35) — id-shape
  validation. ADR-013 explicitly forbids a URL-only regex.
• SceneRegistry (src/runtime/registry.ts:21) — has / get are the
  only way to resolve existence; ADR-002 §Navigation makes the registry
  the single addressability path.
• resolveComposition (src/runtime/composition-resolver.ts:286) —
  drives preload → create → timeline → cleanup. The lifecycle bridge in
  url-navigation.ts builds a one-entry CompositionManifest and calls
  this function so the URL path inherits PUL-F004's resolver invariants
  (mandatory cleanup, error wrapping, abort-checkpoint forwarding).
• SceneModule (src/runtime/scene.ts:60) — return type for the
  navigation target.
• Error-prefix grammar pattern from composition-resolver.ts:182 —
  consistent <subsystem> failed: <detail> prefix so callers pattern
  match on origin.

Clause-by-clause verification preview

Statement: "When the scene URL parameter is present, the runtime SHALL
load the addressed scene as the navigation target."

• "scene URL parameter is present" → detection in
  resolveSceneNavigationTarget via URLSearchParams.getAll('scene').
• "load the addressed scene" → lifecycle execution via
  loadSceneNavigationTarget → resolveComposition with the single-entry
  manifest.
• "as the navigation target" → SceneNavigationTarget data shape +
  return value of resolveSceneNavigationTarget.

ADR-013 guardrails (each pinned by a specific test case):

• Parse once at boundary → input normalization in
  resolveSceneNavigationTarget.
• No URL-only regex → reuses isKebabIdentifier.
• Existence via registry only → registry.has / registry.get calls.
• Errors before lifecycle → tested by recording lifecycle call sites
  and asserting they are never reached on failure paths.
• Lifecycle preserved → tested via loadSceneNavigationTarget +
  resolveComposition integration test.
• URL state authoritative (no fallback) → tested by ensuring scene
  absence returns null, not a stored value.
• Repeated params handled explicitly → tested with ?scene=a&scene=b.
• Orthogonality with mode / composition / index / beat →
  tested by including those params in the URL and asserting they do
  not change the resolved target.
• index not identity when scene supplied → tested in the
  orthogonality block.

Verification

• pnpm lint && pnpm typecheck && pnpm test (the workflow's
  completion_command).
• pre-commit run --all-files.
• New test file targets all clauses and edge cases above.