20. Appendix

Gaps AP-01 through AP-04

Four documented, non-blocking gaps were found during the framework's Phase 4 certification audit and are tracked openly rather than silently fixed. This guide standardizes on this four-item list (see §1.5 for why source documents count these inconsistently).

• AP-01 — Aspirational pipeline stages (live defect in a doc comment, not the code path itself). BackgroundJobExecutionPipeline's own XML doc comment describes a fully-staged sequence (tenant context → distributed lock → logging → tracking → executor → unwind → notification → tracking → lock release → logging) that the shipped RunAsync does not implement. The real method is only a cancellation check, invoking the next delegate, and classify-and-rethrow on exception. A future engineer reading only the docstring could wrongly assume every job automatically gets tenant scoping, a lock, and a notification "for free" by going through the pipeline — it does not; these remain opt-in, manually composed per job. See §4.
• AP-02 — Computed-and-discarded classification value. The pipeline's exception handler calls _failureClassifier.Classify(ex), assigns the result to _, and immediately re-throws — the Transient/Permanent/Cancelled classification is computed on every failure and thrown away before anyone can act on it. See §4.2.
• AP-03 — Permanent no-op notification adapter. BackgroundJobNotificationBoundaryAdapter (the registered IBackgroundJobNotificationAdapter implementation) is a literal Task.CompletedTask no-op, despite ADR-006 intending a real adapter routing job-completion notifications through the Notification Framework. It has never been exercised because all six migrated jobs dispatch notifications directly from inside their own worker/service instead of through this adapter. See §15.4.
• AP-04 — Undocumented reliance on Hangfire's default retry policy. None of the six migrated jobs configures [AutomaticRetry(...)] explicitly — whole-job-failure retry behavior is entirely Hangfire's own library default, inherited implicitly rather than chosen deliberately, for every one of the six jobs. A direct consequence of AP-01/AP-02: the failure-classification output that could inform a deliberate policy is never consumed. See §5.6.

A fifth, separately-tracked structural/organizational deviation exists alongside these four: a single consolidated Shumoul.BackgroundJobs.Tests project rather than three separate ones — accepted at certification as a documented, non-blocking deviation, not a defect.

Enums

Enum	Values
BackgroundJobStatus	Pending=1, Processing=2, Succeeded=3, Failed=4, Cancelled=5, AwaitingRetry=6
BackgroundJobTriggerType	FireAndForget=1, Delayed=2, Recurring=3, Continuation=4
BackgroundJobPriority	Low=1, Normal=2, High=3, Critical=4
BackgroundJobFailureCategory	Transient=1, Permanent=2, Cancelled=3

See §12.1 for the enums in context alongside their sibling records.

Package list

Package	Version	Purpose
Shumoul.BackgroundJobs.Contracts	1.0.0	Enums, records, DTOs
Shumoul.BackgroundJobs.Abstractions	1.0.0	Every interface
Shumoul.BackgroundJobs.Core	1.0.0	The runtime engine
Shumoul.BackgroundJobs.Adapters	1.0.0	Framework-owned infrastructure adapters
Shumoul.BackgroundJobs	1.0.0	Entry point (DI wiring)
Shumoul.BackgroundJobs.Tests	unpublished	Framework's own test suite (200/200 passing)

Terminology / Glossary

Term	Meaning
Golden Reference	The platform's certification tier for a fully extracted, standalone, versioned framework module, audited against actual shipped code
Execution/runtime shape	This framework's module category — owns no domain data, only runtime primitives — as distinct from the Notification Framework's data/delivery shape
Pipeline	The orchestration layer every job execution routes through — IBackgroundJobExecutionPipeline
Execution Context	The immutable, per-execution data holder carrying job ID, tenant, trigger type, correlation ID, priority, and cancellation token
Two-Tier Adapter Model	Framework-owned infrastructure adapters (host-agnostic) vs. host-owned job-specific adapters (business-specific)
Pipeline Job	The host-owned Hangfire-callable bridge class (e.g. CampaignSchedulerPipelineJob) that constructs a context and invokes the pipeline
Job Adapter	The host-owned class implementing IBackgroundJob that translates the generic executor call into exactly one call to a pre-existing business worker method
Claim	An atomic, per-row database update (WHERE Status = Pending AND WorkerToken IS NULL) that prevents duplicate processing of a specific business entity — owned by the domain framework, never by Background Jobs
LTS	Long-Term Support — a documentation/process certification freezing the public API surface and naming a support boundary; does not change runtime behavior
Deferred (governance status)	Explicitly out of scope for the current initiative, requiring a new approved initiative to begin — distinct from "permanently excluded by ADR"

Reference links

Resource	Location
Executive Summary	docs/ARCHITECTURE/BACKGROUND_JOBS_EXECUTIVE_SUMMARY.md
Golden Reference Standard	docs/ARCHITECTURE/BACKGROUND_JOBS_GOLDEN_REFERENCE_STANDARD.md
LTS Release	docs/ARCHITECTURE/BACKGROUND_JOBS_LTS_RELEASE.md
Initiative Closure	docs/ARCHITECTURE/BACKGROUND_JOBS_INITIATIVE_CLOSURE.md
Ownership Matrix (frozen)	docs/ARCHITECTURE/BACKGROUND_JOBS_OWNERSHIP_MATRIX.md, BACKGROUND_JOBS_OWNERSHIP_FINAL.md
Change Policy	docs/ARCHITECTURE/BACKGROUND_JOBS_CHANGE_POLICY.md
Public API Freeze	docs/ARCHITECTURE/BACKGROUND_JOBS_PUBLIC_API.md
Anti-Patterns	docs/ARCHITECTURE/BACKGROUND_JOBS_ANTI_PATTERNS.md
ADRs 003–006	docs/ARCHITECTURE/adr/ADR-003-*.md through ADR-006-*.md
Platform Architecture Standard	docs/ARCHITECTURE/STANDARDS/SHUMOUL_ARCHITECTURE_STANDARD.md
Golden Reference Program	docs/ARCHITECTURE/STANDARDS/SHUMOUL_GOLDEN_REFERENCE_PROGRAM.md
Campaign Execution Claiming	docs/ARCHITECTURE/CAMPAIGN_EXECUTION_CLAIMING.md

Verification Notes

Every fact in this guide was drawn from the platform's existing architecture record and cross-checked against current source in Shumoul.Saas.BackgroundJobsFramework and its integration in Shumoul.Saas.Api. Several genuine discrepancies were found during that verification and are recorded here rather than silently resolved one way:

• Gap count inconsistency. The Golden Reference Standard document's own header states "two" non-blocking gaps while its own body lists three, the Executive Summary states "four," and the Compliance Checklist separates them into "3 carried forward + 2 additionally observed." This guide standardizes on the four-item AP-01–AP-04 list used by the framework's own Roadmap and Anti-Patterns documents, plus a separately-named structural deviation (single Tests project).
• Test-count arithmetic. The migration phase documents state a running BackgroundJobsTests total of 82 after Phase 3.7 and 100 after Phase 3.9 — but 82 + 17 (Phase 3.9's own stated new-test count) = 99, not 100. Neither source document explains the discrepancy. This guide reports each phase's own stated figure rather than asserting a computed running total. The subsequent 100 + 21 (Phase 3.11) = 121 does cross-check cleanly against the separately-cited 121/121 baseline used from that point forward.
• TEST_STRATEGY.md and REGRESSION_MATRIX.md describe the Notification Framework, not this one. Both documents live in the same folder as every Background Jobs document but their content — test project names, regression rows — belongs entirely to the Notification Framework. This guide's Testing chapter draws Background Jobs test evidence from the migration phase documents instead, where it actually lives.
• The framework repository's own CHANGELOG.md and some Phase 2B.3 documents understate current integration progress. They describe ERP host integration as "in progress" or pending later-phase approval, but current source shows all six production migrations are already complete and live. Treat the ERP repository's own phase documents (Phase 3.1 through 3.11) as the more current source of truth for host-integration status.
• The pipeline's own XML doc comment describes a fully-staged sequence the shipped code does not implement — this is AP-01 itself, and this guide's Runtime Pipeline chapter documents the actual behavior as primary, with the aspirational sequence clearly labeled as such rather than presented as current behavior.
• IBackgroundJobTrackingAdapter is referenced only in code comments as forward-looking work — no such interface, class, or file exists anywhere in the repository today. It is not part of the public API and is not documented as an existing type anywhere in this guide.
• The precise technical risk-rationale for excluding Product Import, Tenant Provisioning, and DatabaseInitializer from the six-job migration scope is not spelled out at a comparative-risk level in the documents reviewed — the best-supported explanation is a scope/governance boundary (these three were never inside the initiative's Phase 0.5 ownership-freeze scope), not a documented technical risk comparison against the six jobs that were migrated. See §14.5.

If you find a discrepancy between this guide and current source, trust current source, and treat this guide as needing an update.