prometeu-studio/docs/packer/pull-requests/PR-21-point-in-memory-snapshot-updates-after-write-commit.md

PR-21 Point In-Memory Snapshot Updates After Write Commit

Domain Owner: docs/packer Cross-Domain Impact: docs/studio

Briefing

The current write path still rebuilds the whole project runtime snapshot after a successful point write such as REGISTER.

That is too expensive for the runtime model we want.

Studio refresh on top of an already-updated in-memory snapshot is acceptable. Full filesystem rescan inside the packer after every point write is not.

This PR replaces the normal post-write full refresh path with point snapshot updates in memory, while keeping full reload available only as an explicit recovery fallback.

Objective

Remove whole-project runtime rescan from the normal point write path and replace it with point in-memory snapshot updates after durable commit.

Dependencies

• ./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md
• ./PR-15-snapshot-backed-asset-query-services.md
• ./PR-16-write-lane-command-completion-and-used-write-services.md
• ./PR-20-asset-action-capabilities-and-register-first-delivery.md

Scope

• add explicit point snapshot update support to the runtime registry
• keep the write lane as the only owner of point runtime mutation after durable commit
• replace post-write runtimeRegistry.refresh(project) in the active write path with point snapshot patching
• deliver the first point patch for REGISTER
• keep Studio refresh behavior unchanged

Non-Goals

• no background divergence detection
• no reconcile loop
• no change to Studio refresh semantics
• no broad event model redesign
• no speculative patch implementation for unused write actions

Execution Method

1. Extend the runtime registry so it can update a loaded project snapshot by applying a point patch function inside the packer-owned write flow.
2. Keep full snapshot reload available as recovery fallback, but do not use it in the normal successful point write path.
3. Model a point patch for REGISTER that:
   • appends the new registry entry to the in-memory registry view
   • updates the matching runtime asset from unregistered to registered
   • preserves the rest of the snapshot untouched
4. Apply the patch only after the durable disk commit succeeds.
5. Keep read services unchanged from the Studio point of view; they should continue reading from the runtime snapshot.
6. Keep Studio free to refresh list/details after write completion, because those reads now hit the already-updated in-memory snapshot.
7. Add regression coverage proving that REGISTER no longer depends on whole-project rescan to become visible to subsequent reads.

Acceptance Criteria

• successful point writes no longer trigger whole-project runtime rescan in the normal path
• the runtime registry supports point in-memory snapshot updates after durable commit
• REGISTER updates the loaded project snapshot in place
• subsequent listAssets, getAssetDetails, and getAssetActions read the updated state from memory
• Studio refresh after REGISTER remains valid and does not require frontend-local state patching
• full reload remains available only as fallback or explicit recovery path

Validation

• packer tests for point snapshot patching on REGISTER
• packer tests proving read-after-write coherence without full runtime rebuild
• regression tests for fallback safety when point patching cannot be applied
• Studio smoke validation confirming existing refresh behavior still works on top of the updated runtime snapshot

Affected Artifacts

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**
• prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**
• prometeu-studio/src/main/java/p/studio/**