Chore/curation sync main

[danhdoan]

Summary

• Problem: sync with main (commit 31dc9795)

Test plan

• Coverage added:
  • Unit test
  • Integration test

User-visible changes

None

Checklist

• Tests added or updated and passing (npm test)
• Lint passes (npm run lint)
• Type check passes (npm run typecheck)
• Build succeeds (npm run build)
• Commits follow Conventional Commits format
• Documentation updated (if applicable)
• No breaking changes (or clearly documented above)
• Branch is up to date with main

Risks and mitigations

None

[github-actions]

Claude finished @danhdoan's task in 3m 48s —— View job

---

PR Review

Tasks

• Gather context and understand the PR
• Review source file changes
• Review test file changes
• Post inline comments for specific issues
• Post overall summary with score

---

Summary

Score: 4 / 5

This is a well-engineered sync that lands three distinct optimizations with strong rationale and test coverage. The changes are coherent, the comments explain the why (not just the what), and the test suite pins the central correctness invariants precisely.

---

What's good

Prompt caching strategy (LLM layer)
Moving dateTime from the system prompt into the iter-0 user message is the correct Anthropic caching pattern. The byte-stable system prefix now caches cleanly across iterations. The buildDateTimePrefix() helper is well-isolated and tested. The prependCachedSystemMessage() approach (passing the system prompt through the messages[] array with cache_control: ephemeral) is the right workaround for the AI SDK's lack of providerOptions support on the top-level system: string. Adding cache_control to the last tool in toAiSdkTools to cache the entire tool block is also correct.

Batched abstract generation (abstract-queue.ts / abstract-generator.ts)
The 10× LLM call reduction (2N → 2 per batch cycle) is solid. CDATA wrapping for file content injection prevention is a thoughtful security measure — XML/HTML/JSX docs with literal </document> or </file> markers would have silently broken the prompt envelope without it. The parser anchored on <file path="..."> openers (not </file> closers) correctly handles model overviews that mention closing tags in prose. The drainRequested flag elegantly solves the partial-batch buffering problem at curate-end.

Deferred summary cascade / atomic drain (dream layer)
The A ∪ B merge (drained queue + snapshot diff, deduped) in DreamExecutor is clean. The atomic drain (RMW clears the queue in the same transaction that reads it) correctly avoids the race where a concurrent enqueue during propagation would be lost. The re-enqueue on propagation failure is the right recovery path. DreamTrigger's activity gate bypass when staleSummaryPaths.length > 0 correctly unblocks low-activity projects (ENG-2485).

---

Issues raised (inline)

Severity	File	Description
suggestion	abstract-queue.ts:221	Model-omitted files get empty strings written to disk and counted as processed — existing abstract content silently overwritten with no retry. Consider skipping writeFile when content is empty.
issue	abstract-generator.ts:260	Return array maps over the original (possibly duplicate-path) items, not the deduped set. Intentional for queue alignment — worth documenting in the JSDoc signature.
nitpick	ai-sdk-message-converter.ts:85	The cache-control landing point depends on Object.entries() insertion order. The invariant ("last tool by registration order") is invisible to callers. Consider a comment spelling out the stability guarantee.
nitpick	curate-executor.ts:399	DreamStateService is instantiated directly in propagateAndRebuild rather than injected — diverges from the DreamExecutorDeps DI pattern. Low risk given prototype stubbing in tests covers it.

---

Minor observations

• The removal of the three dream-lock tests in curate-executor.test.ts is correct — the old lock-around-propagation contract no longer applies since propagation is deferred to dream. The new ENG-2485 invariant tests (propagateStaleness must NOT be called on the curate path) are the right replacements.
• StaleSummaryEntrySchema with z.string().min(1) correctly rejects empty paths at the schema boundary. The comment explaining why ("malformed diff entry would resolve to an empty parent dir") is the right level of documentation.
• readOrInit now returns {...EMPTY_DREAM_STATE} instead of {...EMPTY_DREAM_STATE, pendingMerges: []} — correct cleanup since EMPTY_DREAM_STATE already includes pendingMerges: [] and now staleSummaryPaths: [].

[ncnthien]

good

The base branch was changed.