feat(core): reactor subscribes to source.synced and runs per-unit extract (#29)

[mroops0111]

Closes #29.

Summary

When a sync brings new or changed intent units into a workspace, ReactorService dispatches the active ontology's per-unit skill against each, runs one checkpoint pass once they settle, and writes observations to the SourceUnitState ledger so the diff stays consistent. HITL is preserved: the per-unit skill still emits Proposals into the pending inbox.

Studio gains two surfaces consuming the same ledger: a top-of-app banner showing the active reactor pass progress, and per-option freshness badges (Nm ago green / stale amber / nothing) on the source-intent picker. The diff endpoint that drives the badges is the same one the reactor consumes internally via a shared computeSourceDiff helper, so the picker and the reactor can never disagree about what is fresh.

Flowchart

flowchart TD
  A["source.synced event"] --> B{role === 'intent'?}
  B -- no --> X1["drop (no event emitted)"]
  B -- yes --> C{ontology has<br/>batch.perUnit.skillId?}
  C -- no --> X2["drop"]
  C -- yes --> D["computeSourceDiff(workspace, sourceId)<br/>= intentLister + digest + diffAgainst(ledger)"]
  D --> E{new + changed<br/>units empty?}
  E -- yes --> Y0["emit reactor.completed<br/>{ totalUnits: 0, checkpointRan: false }"]
  E -- no --> F{exceeds<br/>maxRunsPerHour<br/>in last 1h?}
  F -- yes --> Y1["emit reactor.throttled<br/>{ limit }"]
  F -- no --> G["record dispatch timestamp<br/>emit reactor.dispatched { totalUnits }"]
  G --> H["sequential loop:<br/>for each unit in (new ∪ changed):<br/>skillRunner.start(perUnit.skillId, args)<br/>+ waitForCompletion<br/>+ recordObservation(ledger)"]
  H --> I{any per-unit<br/>succeeded?}
  I -- no --> Y2["emit reactor.completed<br/>{ checkpointRan: false }"]
  I -- yes --> J{ontology has<br/>checkpoint.skillId?}
  J -- no --> Y2
  J -- yes --> K["skillRunner.start(checkpoint.skillId)<br/>+ waitForCompletion"]
  K --> Y3["emit reactor.completed<br/>{ checkpointRan: true }"]

Loading

Key invariants visible in the chart: per-unit failures do NOT block subsequent units (they keep running); the checkpoint runs at most once per pass and only when at least one per-unit succeeded; the throttle check happens after the diff so a sync that ends up empty does not consume a dispatch slot.

Locked decisions

These were discussed and answered on the issue before implementation started. Captured here so the PR review does not relitigate them.

Per-unit, not batched. A sync that brings in ten changed issues dispatches ten separate braid-extract subprocesses, not one batched extract. Batching would undo the per-document isolation #43 just shipped.

Sequential, no concurrency. Per-unit dispatches run in strict order so a sprint of ten unit changes never spikes LLM concurrency past one worker. Combined with maxRunsPerHour: 5 this gives two layers of cost containment.

First-ingest does NOT fire reactor. The operator drives the initial Run Batch explicitly, where the cost preview is visible. Once a source is connected, subsequent cmd.syncSource deliveries flow through the reactor normally.

Reactor only fires for role: 'intent' sources. Code-only diffs do not trigger re-extract because the per-unit skill consumes intent units; re-running it because code beneath an unchanged intent unit changed would produce non-deterministic LLM noise without semantic gain. Stale cross-references between intent and code are handled by the checkpoint pass that fires after per-unit dispatches settle. Workspaces whose intent stream is sparse should lean on an intent-shaped loader (see #61 for the planned PR-descriptions-as-intent source) rather than asking the reactor to scan code.

No gate assumption. The reactor emits reactor.completed once the per-unit and checkpoint passes settle and leaves the question of who applies the resulting proposals to upstream layers. A future generative axis can attach an apply(gate: auto) consumer to the same event.

Test plan

• pnpm --filter @braidhq/core test — 217 pass, including 7 new ReactorService tests covering 3-new-units → 3 sequential dispatches + 1 checkpoint, no-checkpoint-when-no-success, strict sequential ordering proof (unit N+1 does not start until unit N finishes), role-filter rejection for role: 'code', throttle after maxRunsPerHour in a rolling 1h window, no-op completed{0} when the diff is empty, dispose-detaches-listener.
• pnpm --filter @braidhq/server test — 290 pass.
• pnpm --filter @braidhq/studio typecheck — clean.
• pnpm lint — clean.
• Dogfood: enable reactor on this repo's own workspace by adding reactor: { enabled: true } to PRODUCT.md, restart server, close a roadmap issue, and confirm: (a) the new top-of-app banner shows the reactor pass while it runs; (b) a new pending proposal appears in the inbox without any CLI invocation; (c) the source-intent picker option for the closed issue shows Nm ago (green) right after; (d) editing an issue and re-syncing turns the badge amber (stale) before the next reactor pass clears it.

Notes for review

The reactor and the diff endpoint share a single computeSourceDiff helper so the two surfaces always partition the same way. Studio's banner uses its own EventSource subscription rather than threading state through useWorkspaceEvents; that hook continues to be a pure side-effect cache invalidator. The picker badge join happens client-side via two useQueries (diff + ledger states) deduped by react-query, so multiple options for the same source share a single network round trip.

🤖 Generated with Claude Code