Back to feed

sledtools/pika branch #56

pika-git-boundary-1

Document pika-git and pikaci boundaries

Target branch: master

Merge Commit: 9f5e2aa82cc1d67763c9fa7b165758dee4a62b11

branch: merged tutorial: ready ci: success
Open CI Details

Continuous Integration

CI: success

Compact status on the review page, with full logs on the CI page.

Open CI Details

Latest run #72 success

head b576b0be7969a6d0d41f2a288ef676a74b4b9ff6 · queued 2026-03-25 19:26:41 · 0 lane(s)

queued 0s

No lanes were selected for this branch head.

Summary

This branch introduces a dedicated design document (todos/pika-git-pikaci-boundary.md) that codifies the architectural boundary between pika-git (the forge/scheduler layer) and pikaci (the CI execution engine). It establishes that pika-git owns queue truth, leases, target health, operator recovery, and lane status, while pikaci owns run execution, timeout enforcement, durable run/job records, and structured lifecycle events. The existing todos/pika-git.md roadmap is updated to reference this new boundary document, replace open-ended exploration in Workstream 4 with the concrete conclusion, add a summary section of the boundary answer, and revise the Phase 2 direction to recommend extracting forge_runtime before forge_service and both before the pika-news → pika-git rename.

Tutorial Steps

Add the pika-git / pikaci boundary design document

Intent: Create a single authoritative reference that maps current code ownership across pika-git and pikaci, defines which states are authoritative in each system, describes the failure taxonomy split, and lays out the extraction order for future refactoring.

Affected files: todos/pika-git-pikaci-boundary.md

Evidence 
@@ -0,0 +1,207 @@
+# Pika Git / Pikaci Boundary
+
+This is the short design note for the current `pika-git` ↔ `pikaci` seam.

A new file todos/pika-git-pikaci-boundary.md is added with 207 lines covering the full boundary design. The document is grounded in the current codebase, referencing specific files:

  • crates/pika-news/src/web.rs — live app state, route handlers, background wake loop
  • crates/pika-news/src/ci.rs — lane claiming, worker launching, lease fencing
  • crates/pika-news/src/branch_store.rs — lane status, execution reason, failure kind, claim tokens, target health
  • crates/pikaci/src/run.rs — durable run records, RunLifecycleEvent
  • crates/pikaci/src/executor.rs — per-job execution, timeout enforcement
  • crates/pikaci/src/model.rs — structured run/job/event surface

The document is organized into these major sections:

  1. Boundary in one sentence — pika-git owns scheduling and operator-visible CI state; pikaci owns executing a claimed run to a terminal outcome.
  2. What each side owns — explicit lists of responsibilities.
  3. Authoritative states — forge-authoritative (lane status, execution reason, failure kind, target health) vs. pikaci-authoritative (run/job status, timestamps, messages, log locations).
  4. Failure taxonomy — pikaci classifies executor-local outcomes (passed, failed, timed out, infrastructure failure); pika-git maps those into forge lane failure kinds and target-health effects.
  5. Target health and queue reasons — belong in forge because only forge sees the whole queue, branch/nightly priorities, and concurrency-group contention.
  6. Cancellation and stale-run recovery — forge lease fencing is the primary correctness boundary; executor cancellation is best-effort cleanup.
  7. Manual recovery ownership — queue-truth mutations belong to pika-git/ph; executor-local cleanup belongs to pikaci.
  8. API/protocol direction — extend the existing --output jsonl lifecycle events with explicit failure kind, optional heartbeat, and optional cancel-by-run-id. Avoid anti-patterns like log parsing for scheduler state.
  9. Extraction order — forge_runtime first, then forge_service, then typed models, then persistence split.
  10. Immediate next steps — ship current UX fixes, extract forge_runtime, move recovery behind forge_service, then rename.

Reference the boundary document from the architectural boundary section in pika-git.md

Intent: Cross-link the new boundary document from the existing roadmap so readers of pika-git.md can find the authoritative boundary answer without searching.

Affected files: todos/pika-git.md

Evidence 
@@ -207,6 +207,8 @@ The next iteration should converge on these boundaries:
+The current grounded boundary answer lives in [pika-git-pikaci-boundary.md](pika-git-pikaci-boundary.md).

A single line is inserted after the existing boundary convergence list (around line 209) that links to the new document. This ensures the roadmap section on boundaries points to the detailed design note rather than restating it.

Replace open-ended Workstream 4 with concrete conclusion

Intent: Mark the pika-git/pikaci boundary exploration as answered, replacing the previous open investigation items with a summary of conclusions and a pointer to the detailed document.

Affected files: todos/pika-git.md

Evidence 
@@ -327,26 +329,45 @@
-### Workstream 4: Pika Git / Pikaci boundary plan
-
-- map current ownership and responsibility seams
-- define the desired future boundary
-- identify the typed failure and status model needed between them
+### Workstream 4: Pika Git / Pikaci boundary plan
+
+- current answer is now written down in [pika-git-pikaci-boundary.md](pika-git-pikaci-boundary.md)
+- key conclusion:
+  - forge owns queue truth, leases, queue reasons, target health, and operator recovery
+  - `pikaci` owns terminal execution, durable run/job records, logs metadata, and lifecycle events
+- next step is implementation cleanup, not more open-ended exploration

Workstream 4 previously contained three open investigation bullets (map ownership, define boundary, identify typed model). These are replaced with:

  • A reference to the boundary document.
  • A two-bullet key conclusion summarizing the forge vs. pikaci split.
  • A clear statement that the next step is implementation cleanup, not further exploration.

This signals to the team that the design question is answered and work can proceed to execution.

Add a standalone boundary answer summary section

Intent: Provide a quick-reference summary of the boundary answer directly in the roadmap so readers do not need to open the full boundary document for the high-level takeaway.

Affected files: todos/pika-git.md

Evidence 
@@ -329,45 +329,45 @@
+## Boundary Answer We Have Now
+
+We now have a concrete answer for the `pika-git` ↔ `pikaci` seam.
+
+The short version:
+
+- `pika-git` owns scheduling, leases, queue reasons, target health, and operator-visible CI truth
+- `pikaci` owns run execution, timeout enforcement, run/job records, and structured lifecycle events
+- stale-run correctness should continue to come from forge lease fencing first; executor cancelation is a cleanup path, not the primary safety boundary
+- target health policy stays in forge because only forge sees the whole queue

A new ## Boundary Answer We Have Now section is inserted into pika-git.md. It contains four bullet points covering:

  1. What pika-git owns (scheduling, leases, queue reasons, target health, operator CI truth).
  2. What pikaci owns (execution, timeouts, run/job records, lifecycle events).
  3. The stale-run correctness model (forge lease fencing is primary; executor cancel is cleanup).
  4. Why target health stays in forge (only forge sees the whole queue).

It also includes a guardrail statement: the next cleanup should not try to make pikaci into a queue manager.

Revise Phase 2 direction with concrete extraction order

Intent: Replace the tentative Phase 2 sketch with a specific ordered plan that reflects the boundary conclusions, prioritizing forge_runtime extraction before forge_service and both before the rename.

Affected files: todos/pika-git.md

Evidence 
@@ -329,45 +329,45 @@
 ## Likely Phase 2 Direction
 
-We should not lock phase 2 yet.
+We still should not over-lock phase 2, but the next extraction order is clearer now.
 
-But the likely implementation direction after phase 1 is:
+Recommended order:
 
-1. restore the branch review UI and CI details shape
-2. add operational recovery tooling in UI and `ph`
-3. extract runtime and service boundaries
-4. introduce typed models and cleaner persistence boundaries
-5. harden anti-stall behavior across `pika-git` and `pikaci`
-6. finish legacy cleanup and naming cleanup
+1. finish the current UX and dogfooding reliability fixes
+2. extract `forge_runtime` first
+   - centralize wake reasons, CI scheduling, mirror scheduling, and forge health
+3. extract `forge_service`
+   - move merge / close / rerun / recover / detail assembly out of handlers
+4. expand typed forge models across the touched paths
+5. split persistence by forge domain
+6. harden the forge/`pikaci` protocol with explicit failure kind and optional cancel/progress additions
+7. finish legacy cleanup and naming cleanup

The previous Phase 2 section listed six loosely-ordered steps and deferred sequencing to after Phase 1. The updated version:

  1. Finish current UX/reliability fixes — no refactor until dogfooding gaps are closed.
  2. Extract forge_runtime — centralize wake reasons, CI scheduling, mirror scheduling, and forge health. This comes first because the background wake/schedule/mirror ownership in web.rs is the highest-risk coupling.
  3. Extract forge_service — move merge/close/rerun/recover/detail assembly out of route handlers.
  4. Expand typed forge models — queue reason, failure kind, branch/CI DTOs.
  5. Split persistence by domain — branches, CI runs/lanes, inbox, mirror, auth.
  6. Harden forge/pikaci protocol — explicit failure kind, optional cancel, optional progress.
  7. Finish legacy and naming cleanup — last because it depends on stable boundaries.

The closing statement emphasizes the key ordering constraint: forge_runtime before forge_service, both before the rename.

Diff