relayburn-sdk: port the ingest verb

[willwashburn]

Summary

Fill in `crates/relayburn-sdk/src/ingest_verb.rs` with the async `ingest` verb in both forms:

• `LedgerHandle::ingest(&mut self, opts) -> Result`
• free `pub async fn ingest(opts) -> Result`

Both delegate to `relayburn_ingest::ingest_all`. The free function opens its own ledger via `Ledger::open(LedgerOpenOptions { home: opts.ledger_home, ..Default::default() })`. `IngestOptions` exposes `ledger_home`, `roots`, and the boxed `on_progress` / `on_warn` sinks the lower crate already supports.

The Rust port threads the ledger location through `Ledger::open` explicitly rather than swapping `RELAYBURN_HOME` (the TS sibling did the env-var dance), so embeddings can run multiple ledgers per process.

Per-harness verbs (`ingest_claude_projects`, etc.) intentionally not wrapped here — scoped to `ingest_all`; can be a follow-up.

Part of #246.

Test plan

• `cargo test -p relayburn-sdk` — new `#[tokio::test]` passes (empty roots → all-zero `IngestReport`)
• `cargo test --workspace` green

Stacking

Stacked on #300 (module stubs) — base is `claude/sdk-module-stubs` and will rebase to `main` once that lands.

🤖 Generated with Claude Code

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Replaces placeholder ingest verb with full async implementation in the SDK. Introduces IngestOptions struct and callback sink type aliases (ProgressSink, WarnSink). Adds LedgerHandle.ingest() method and free ingest() function that orchestrate ingestion by delegating to relayburn_ingest::ingest_all. Includes unit tests validating behavior with empty roots.

Changes

Ingest Verb Implementation

Layer / File(s)	Summary
Public API Types crates/relayburn-sdk/src/ingest_verb.rs	Introduces ProgressSink and WarnSink callback type aliases for progress and warning reporting. Adds IngestOptions struct with ledger_home, roots, on_progress, and on_warn fields.
Core Implementation crates/relayburn-sdk/src/ingest_verb.rs	Adds IngestOptions::into_raw() conversion to underlying raw options. Implements LedgerHandle.ingest() async method and free ingest() async function that open ledgers and invoke relayburn_ingest::ingest_all.
Tests & Validation crates/relayburn-sdk/src/ingest_verb.rs	Unit tests verify ingestion with empty roots returns zero counts for scanned sessions and appended turns. Tests set up RELAYBURN_HOME environment for proper ledger initialization.

Sequence Diagram

sequenceDiagram
    participant Client
    participant SDK as SDK<br/>(LedgerHandle)
    participant Ingest as relayburn_ingest
    participant Ledger
    
    Client->>SDK: ingest(options)
    SDK->>SDK: Open ledger if needed<br/>(LedgerOpenOptions)
    SDK->>SDK: Convert IngestOptions<br/>to RawIngestOptions
    SDK->>Ingest: ingest_all(raw_opts, ledger)
    Ingest->>Ledger: scan & ingest
    Ingest-->>SDK: IngestReport
    SDK-->>Client: Result<IngestReport>

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• AgentWorkforce/burn#246: PR directly implements the async ingest verb with SDK public API types and methods that address this issue's objective.

Possibly related PRs

• AgentWorkforce/burn#300: PR replaces the stub ingest verb header introduced in #300 with the complete implementation.
• AgentWorkforce/burn#299: PR extends the LedgerHandle scaffold added in #299 by implementing the ingest method.
• AgentWorkforce/burn#297: PR's ingest functions delegate to relayburn_ingest::ingest_all, which #297 implements.

Poem

🐰 The Ledger hops into async delight,
With IngestOptions and sinks shining bright,
A whisker of progress, a thump of the warn,
Our ingest verb rises, new-fashioned and born! 🌱

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'relayburn-sdk: port the ingest verb' is concise, clear, and directly describes the main change—implementing the ingest verb in the relayburn-sdk module. It accurately reflects the primary objective of the PR.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset. It explains the implementation details, design decisions (explicit ledger path instead of env vars), testing approach, and context (stacking, issue reference), all of which correspond to the actual changes made.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/sdk-ingest-verb

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 458c862f0d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve ledger_home for ingest side effects

into_raw drops ledger_home, but ingest_all still performs home-scoped side effects via cleanup_stale_pending_stamps() and load_config() (in crates/relayburn-ingest/src/ingest.rs), both of which resolve paths from RELAYBURN_HOME. As a result, calling ingest with a non-default ledger_home can clean pending stamps and read content settings from the wrong ledger, violating the SDK contract for multi-ledger embeddings and potentially mutating another ledger’s state.

Useful? React with 👍 / 👎.