prometeu-studio/docs/packer/agendas/01.5. Incremental Build, Cache, and Watch Model Agenda.md

Incremental Build, Cache, and Watch Model Agenda

Status

Closed

Resolved by 005-incremental-build-cache-and-watch-model-decision.md.

Purpose

Define how packer caches, fingerprints, and optional watch behavior should work without compromising determinism.

Context

The draft proposes:

• fingerprint tracking in assets/.prometeu/cache/fingerprints.json,
• incremental rebuilds,
• strong hashing,
• optional watch mode.

This area is operationally important but easy to underspecify.

Source Sections

• 11. Incremental Build, Cache, and Fingerprints
• 13.10 prometeu packer watch

Key Questions

1. Which fingerprints are authoritative for cache invalidation?
2. When are mtime and size only hints versus hard cache keys?
3. What outputs may be reused from cache, and under which conditions?
4. Does watch mode belong in v1 spec or only as non-normative future work?
5. How should cache invalidation be surfaced to users and diagnostics?
6. How do we guarantee that incremental behavior never changes final outputs?

Options

Option A

Specify cache behavior conservatively and keep watch mode optional or non-normative in the first wave.

Option B

Make watch mode and aggressive incremental behavior part of the early normative contract.

Tradeoffs

• Option A reduces spec risk and keeps determinism easier to enforce.
• Option A allows cache internals to evolve while the artifact contract stabilizes first.
• Option B may be attractive for UX, but it increases the amount of behavior that must be frozen too early.

Recommendation

Adopt Option A:

• deterministic outputs first,
• conservative cache spec,
• watch mode optional until the underlying invariants are stable.

Expected Decisions to Produce

1. Cache authority and invalidation model.
2. Fingerprint contract.
3. Normative versus non-normative status of watch mode.
4. Safety rules for incremental reuse.

Expected Spec Follow-up

• Cache and fingerprints spec.
• Incremental build guarantees spec.
• Optional watch mode spec or deferred note.

Non-Goals

• Full CLI command catalog.
• Asset registry identity rules.
• Cartridge shipper integration.