pikaci: fulfillment invocation seam + wrapper persistence

[justinmoon]

Summary

• Add fulfillment invocation seam and persist fulfillment wrapper path
• Validate helper fulfillment results and harden result handling
• Add dedicated fulfillment helper with result contract
• Subprocess fulfillment mode with explicit embedded binary
• Validate & fulfill prepared output requests
• Remote prepared output prototype with consumer seam
• Staged rust subprocess run mode with rerun preservation
• Shared runtime helpers: welcome publish, group create, key package interop

Test plan

• CI must pass

🤖 Generated with Claude Code

---

Summary by CodeRabbit

• New Features

  • Added prepared output invocation mode selection (direct helper execution or external wrapper command).
  • Status output now displays active invocation mode and wrapper program configuration.
  • Invocation settings persist across reruns and are observable in status output.

• Documentation

  • Updated roadmap with invocation model details and observability enhancements.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces a new PreparedOutputInvocationMode enum to support pluggable fulfillment strategies (direct helper execution vs. external wrapper command) and integrates invocation configuration throughout the pikaci run pipeline. The changes add new fields to RunMetadata and RunRecord, define a PreparedOutputFulfillmentInvoker trait with concrete implementations, and propagate invocation mode and wrapper program parameters through the run execution flow and prepared-output consumption chain.

Changes

Cohort / File(s)	Summary
Model Definition crates/pikaci/src/model.rs	New public enum PreparedOutputInvocationMode (variants: DirectHelperExecV1, ExternalWrapperCommandV1) and two optional fields added to RunRecord: prepared_output_invocation_mode and prepared_output_invocation_wrapper_program.
Core Run Execution crates/pikaci/src/run.rs	New trait PreparedOutputFulfillmentInvoker with concrete implementations (DirectHelperExecPreparedOutputFulfillmentInvoker, ExternalWrapperPreparedOutputFulfillmentInvoker). Extended PreparedOutputConsumer trait to accept invocation mode and wrapper program parameters. RunMetadata gains two new fields. Run execution flow (run_jobs_against_snapshot, run_prepare_nodes, consume_prepared_output_handoff) updated to resolve and propagate invocation mode and wrapper program. New resolver functions and helper text functions added. Tests expanded to cover mode switching, wrapper resolution, and invoker behavior.
CLI Status Display & Metadata crates/pikaci/src/main.rs	Status formatting extended to display prepared_output_invocation_mode and prepared_output_invocation_wrapper_program. New helper function prepared_output_invocation_mode_label added. RunMetadata initialization and rerun metadata preservation updated to handle new invocation fields.
Public Exports crates/pikaci/src/lib.rs	PreparedOutputInvocationMode added to public re-exports in the model block.
Planning Documentation todos/pikaci-staged-ci-plan.md	Phase 6 narrative updated to reference wrapper-shaped invocation seam boundary. Added explicit subsection for helper-invoker slice details covering direct vs. wrapper-based invocation, unchanged request/result contracts, and observability enhancements.

Sequence Diagram(s)

sequenceDiagram
    participant RunJob as Run Job
    participant Resolver as Mode Resolver
    participant WrapperRes as Wrapper Resolver
    participant Invoker as Selected Invoker
    participant Consumer as Prepared Output<br/>Consumer
    participant Record as RunRecord

    RunJob->>Resolver: determine invocation mode<br/>(based on consumer type)
    Resolver-->>RunJob: PreparedOutputInvocationMode
    RunJob->>WrapperRes: resolve wrapper program<br/>(if ExternalWrapperCommandV1)
    WrapperRes-->>RunJob: wrapper path or None

    RunJob->>Invoker: select invoker by mode
    Invoker-->>RunJob: DirectHelperExec or<br/>ExternalWrapper

    RunJob->>Consumer: consume with mode &<br/>wrapper path
    Consumer->>Invoker: invoke(helper, wrapper,<br/>request, result)
    Invoker-->>Consumer: Output
    Consumer-->>RunJob: Result

    RunJob->>Record: store invocation_mode<br/>& wrapper_program
    Record-->>RunJob: persisted

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• pikaci: helper fulfillment result contract + validation #526: Modifies prepared-output fulfillment flow and PreparedOutputConsumer API changes in run.rs, directly overlapping with invocation trait updates.
• pikaci: fulfillment helper + staged subprocess + pika-news fixes #524: Updates prepared-output invocation code paths in run.rs including helper/wrapper handling and invocation mode wiring.
• pikaci: remote prepared output prototype #515: Modifies PreparedOutputConsumer trait signature and run.rs prepared-output record field plumbing, touching the same consumer infrastructure.

Poem

🐰 A helper learns to invoke,
Now direct or wrapped, the modes unlock,
With pluggable invokers bright,
Prepared outputs take flight,
Flexibility in every hop!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly summarizes the main changes: introducing a fulfillment invocation seam and adding wrapper persistence, which are the primary objectives across all modified files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ikjzelql

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.