prometeu-studio/docs/packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md

PR-09 Event Lane, Progress, and Studio Operational Integration

Domain Owner: docs/packer

Briefing

Implement the packer event/reporting lane and bind the production packer service lifecycle into Studio operational surfaces.

This PR is where Studio stops inferring operational history locally and starts reflecting packer-native lifecycle events.

Objective

Deliver the structured packer event lane, progress reporting, and adapter/wiring so Studio Activity, progress, and refresh behavior align with real packer execution.

Dependencies

• ./PR-08-assets-pa-and-companion-artifact-emission.md
• ../specs/5. Diagnostics, Operations, and Studio Integration Specification.md
• cross-domain reference: ../../studio/specs/1. Studio Shell and Workspace Layout Specification.md
• cross-domain reference: ../../studio/specs/4. Assets Workspace Specification.md

Scope

• implement the initial structured event set:
  • asset_discovered
  • asset_changed
  • diagnostics_updated
  • build_started
  • build_finished
  • cache_hit
  • cache_miss
  • preview_ready
  • action_applied
  • action_failed
  • progress_updated
• define the baseline event envelope with fields equivalent to:
  • project_id
  • operation_id
  • sequence
  • kind
  • timestamp
  • summary
  • progress
  • affected_assets
• define event publishing hooks across scan, doctor, mutation, and build flows
• implement the Studio adapter from packer events to Studio event bus semantics
• align global Activity and progress behavior with packer-native lifecycle updates

Non-Goals

• no final watch daemon
• no remote/shared cache orchestration
• no UI redesign

Execution Method

1. Add event publication points to read, mutation, doctor, and build services.
2. Define a packer event sink abstraction so Studio is a consumer, not the owner, of the event model.
3. Preserve operation causality with stable operation_id plus monotonic per-operation sequence.
4. Map packer events into existing Studio Activity and progress surfaces through an adapter, with coalescing only for low-value repeated progress-like events.
5. Verify that long-running work does not block UI interaction and that terminal lifecycle events remain individually visible.

Acceptance Criteria

• packer emits structured lifecycle events across core operations
• Studio Activity/progress can be driven from packer-native events
• mutation and build flows no longer require Studio-local event invention
• event ordering is coherent from the UI perspective
• same-operation event ordering is preserved through the Studio adapter
• adapters may remap event shapes, but do not invent causal relationships or semantic summaries absent from the packer event stream

Validation

• packer event publication tests
• adapter tests from packer events to Studio events
• ordering/coalescing tests for progress-heavy operations and terminal lifecycle events
• Studio smoke validation for Activity and progress during packer-backed operations

Affected Artifacts

• prometeu-packer/**
• prometeu-studio/** event adapter and wiring
• integration fixtures for long-running operations