Document Immediate.Jobs skipped job state

[dukesteen]

Summary

• document the durable Skipped state across lifecycle, continuations, recurring overlap, batches, monitoring, and testing
• document Run now for scheduled invocations and dashboard mutation responses
• document property-backed init payloads and the SkippedCount schema addition
• align lifecycle terminology with the current Active state

Tracks the user-facing changes in ImmediatePlatform/Immediate.Jobs#77, ImmediatePlatform/Immediate.Jobs#80, and ImmediatePlatform/Immediate.Jobs#81.

Validation

• pnpm lint
• pnpm check
• pnpm build

Summary by CodeRabbit

• Documentation
  • Documented new job states, including AwaitingParameters, Active, and Skipped.
  • Clarified batch continuation, skipped-branch propagation, settlement counts, and monitoring behavior.
  • Documented retrying and immediately running scheduled work while preserving attempt history.
  • Clarified recurring-job overlap handling and persisted skipped occurrences.
  • Added guidance for constructor-initialized properties, storage schema migrations, and dashboard response outcomes.
  • Added documentation for cascade-skipping test assertions.

[coderabbitai]

📝 Walkthrough

Walkthrough

The documentation defines Skipped job and batch outcomes, graph branch settlement, batch monitoring counts, dashboard mutation behavior, scheduled-job retries, recurring overlap handling, and public init property support.

Changes

Jobs lifecycle and monitoring

Layer / File(s)	Summary
Lifecycle and graph settlement src/content/docs/Immediate.Jobs/api-reference.md, src/content/docs/Immediate.Jobs/delivery-guarantees.md, src/content/docs/Immediate.Jobs/how-it-works.md, src/content/docs/Immediate.Jobs/batches-and-continuations.md, src/content/docs/Immediate.Jobs/testing-jobs.md	The lifecycle includes AwaitingParameters, Active, and Skipped. Graph settlement releases eligible children and recursively skips unselected branches. Testing helpers document cascade-skipping assertions.
Monitoring and storage contracts src/content/docs/Immediate.Jobs/api-reference.md, src/content/docs/Immediate.Jobs/batches-and-continuations.md, src/content/docs/Immediate.Jobs/configuring-storage-providers.md	BatchStatus exposes settled outcome counts and FractionSettled. Storage guidance documents the non-null SkippedCount migration.
Dashboard operations and mutation responses src/content/docs/Immediate.Jobs/dashboard-and-monitoring.md, src/content/docs/Immediate.Jobs/diagnostics.md, src/content/docs/Immediate.Jobs/delivery-guarantees.md, src/content/docs/Immediate.Jobs/api-reference.md	Dashboard documentation covers skipped work, retries, scheduled execution, preserved attempt data, and 204, 202, 404, and 409 responses.
Recurring jobs and job construction src/content/docs/Immediate.Jobs/recurring-jobs.md, src/content/docs/Immediate.Jobs/how-it-works.md, src/content/docs/Immediate.Jobs/creating-jobs.md	Skipped recurring occurrences are persisted as terminal history. Public init properties are initialized through generated metadata, with runtime deserialization limitations documented.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• ImmediatePlatform/Immediate.Dev#13: Updates the same Immediate.Jobs API, batch, storage, lifecycle, dashboard, recurring-job, and testing documentation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: documenting the durable Skipped job state in Immediate.Jobs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/immediate-jobs-skipped-state

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/content/docs/Immediate.Jobs/configuring-storage-providers.md`:
- Around line 125-126: Update the storage-provider migration documentation to
explicitly require adding the non-null SkippedCount column, backfilling all
existing batch rows with 0, and applying a default of 0 for future inserts
before provider startup.

In `@src/content/docs/Immediate.Jobs/delivery-guarantees.md`:
- Around line 53-63: Clarify the retention precedence for skipped members in
successful batches in the retention documentation near the
BatchSucceededRetention and SucceededRetention descriptions. Explicitly state
which setting controls skipped members when the enclosing batch succeeds, while
preserving the existing batch-as-a-unit deletion behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 36dac156-336c-4201-8b58-ba4f875b0b4b

📥 Commits

Reviewing files that changed from the base of the PR and between 83ce153 and 90201e7.

📒 Files selected for processing (10)

• src/content/docs/Immediate.Jobs/api-reference.md
• src/content/docs/Immediate.Jobs/batches-and-continuations.md
• src/content/docs/Immediate.Jobs/configuring-storage-providers.md
• src/content/docs/Immediate.Jobs/creating-jobs.md
• src/content/docs/Immediate.Jobs/dashboard-and-monitoring.md
• src/content/docs/Immediate.Jobs/delivery-guarantees.md
• src/content/docs/Immediate.Jobs/diagnostics.md
• src/content/docs/Immediate.Jobs/how-it-works.md
• src/content/docs/Immediate.Jobs/recurring-jobs.md
• src/content/docs/Immediate.Jobs/testing-jobs.md