--- id: WF-PFM-DJE-008 title: Run a file job through the bulk lane trigger: A caller submits CRM job input by completed upload identity. product_area: platform module: data-job-engine revision: 1 status: draft design_intent: confirmed origin: >- services-platform:docs/proposals/rhythm-data-job-engine-plan.md §9.1 the two lanes, §10.2 controls (approved 2026-10-12); services-platform:docs/proposals/api-workload-governance/README.md brief 3.1 (bulk admission, approved 2026-10-17); services-platform:docs/jobs.md (durable jobs) implementation_evidence: observed inference: [] source_sha: macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 implements: - CAP-PFM-DJE-011 - CAP-PFM-DJE-012 - CAP-PFM-DJE-013 - CAP-PFM-DJE-014 moves: - STATE-PFM-DJE-001 - STATE-PFM-DJE-002 crosses: - SVC-PFM-DJE-crm-data-jobs - SVC-PFM-DJE-engine - SVC-PFM-DJE-data-jobs - SVC-PFM-DJE-capacity hops: - 'n': 1 actor_or_service: CRM bulk submission action: >- Check the operation, submit authority, completed workspace uploads and any initial-load gate, then persist job and durable execution. anchor: >- services-crm:modules/data-jobs/services/jobs/bulk-data-job-submission.ts:submitBulkDataJob seam: sync on_failure: Refuse inaccessible or incomplete uploads before persistence. left_inconsistent: No partial submission exists. observer: The request response exposes the result. provenance: test source: >- services-crm:modules/data-jobs/tests/e2e/bulk-data-jobs.e2e.spec.js#refuses an upload id of no upload at all in the same words, so neither answer tells a caller whose it is - 'n': 2 actor_or_service: CRM bulk submission action: Start the durable workflow after its database commit. anchor: >- services-crm:modules/data-jobs/services/jobs/bulk-data-job.ts:startBulkDataJob seam: state_machine on_failure: The reconciler settles work whose execution never starts or is lost. left_inconsistent: The data job can remain queued until reconciliation. observer: The job's failure summary; reconciler logs. provenance: documented source: >- services-crm:modules/data-jobs/services/jobs/bulk-data-job.ts (module comment, "What a failure means to the data job") - 'n': 3 actor_or_service: 'Task function, chunkSource' action: >- Stream supported file lines, validate them, write bounded chunks and record source-line refusals. anchor: >- macroservice-libraries:packages/data-jobs/src/bulk-data-job-tasks.ts:chunkSource seam: state_machine on_failure: 'Use task retries, then the workflow failure handler.' left_inconsistent: Produced chunk objects remain until their 14-day expiry. observer: Source progress and line-attributed refusals expose reading outcomes. provenance: test source: >- macroservice-libraries:packages/data-jobs/src/tests/integration/bulk-data-jobs.integration.spec.ts#fails the job when most of the file cannot be read, rather than reading nine million lines of it - 'n': 4 actor_or_service: 'Task function, planBatches' action: Plan one batch per chunk and advance the persisted planning cursor. anchor: >- macroservice-libraries:packages/data-jobs/src/bulk-data-job-tasks.ts:planBatches seam: state_machine on_failure: Use task retry and failure settlement. left_inconsistent: Previously committed planning progress remains available. observer: Inspection exposes persisted planning progress. provenance: observed source: >- macroservice-libraries:packages/data-jobs/src/bulk-data-job-tasks.ts:planBatches - 'n': 5 actor_or_service: 'Task function, admitBatches' action: >- Admit batches within job, workspace and factored service budgets, waiting or detecting stalled capacity. anchor: >- macroservice-libraries:packages/data-jobs/src/bulk-data-job-tasks.ts:admitBatches seam: state_machine on_failure: >- Fail stalled admission with its binding-ceiling reason; zero-factor protection simply holds work. left_inconsistent: Admitted work may finish while unadmitted work is abandoned. observer: Round-by-round admission logs accompany apply progress. provenance: test source: >- macroservice-libraries:packages/data-jobs/src/tests/integration/bulk-data-jobs.integration.spec.ts#fails a job whose ceiling has been held by work that is not moving, rather than waiting for room for ever - 'n': 6 actor_or_service: CRM bulk worker action: >- Execute admitted batches as the submitter using their chunk input and mapping store. anchor: 'services-crm:modules/data-jobs/aws/logic/bulk-data-jobs.lambda.ts' seam: queue on_failure: 'Use normal item, transient and systemic batch handling.' left_inconsistent: Committed units remain after later failure. observer: Results and refusals pages. provenance: documented source: >- macroservice-libraries:packages/data-jobs/README.md#How a service adopts it - 'n': 7 actor_or_service: 'Task function, settleIfDone' action: Recount durable outcomes and settle after all batches finish. anchor: >- macroservice-libraries:packages/data-jobs/src/bulk-data-job-tasks.ts:settleIfDone seam: state_machine on_failure: Fail the execution and data job if settlement exhausts recovery. left_inconsistent: Already committed business records are retained. observer: The job's final state. provenance: observed source: >- macroservice-libraries:packages/data-jobs/src/bulk-data-job-tasks.ts:settleIfDone idempotency: >- Tasks persist their progress cursors and batches use receipts for replay. Submission keys recognize saved deliveries. Workflow loops continue in another execution before reaching the history limit. concurrency: >- Task and worker concurrency are bounded by infrastructure and service budgets. Admission prefers long-waiting jobs and otherwise the workspace with least held work; it is not a simple round-robin guarantee. Paused loops wait and cancelled loops end. branches: - CRM file input has direct application without a preview route. - >- Accepted upload types include JSON documents and archives that these readers cannot consume. waits: - >- Admission normally waits five seconds, twenty when a full ceiling holds it, and twenty while paused. evidence: - >- macroservice-libraries at 54536a44: src/bulk-data-job-tasks.ts, bulk-data-job-workflow.ts, chunk-source.ts, chunk-plan.ts, admission-budget.ts, admission-planner.ts, bulk-data-job-config.ts. - >- services-crm at a8d1364f: services/jobs/bulk-data-job-submission.ts, bulk-data-job.ts, bulk-data-job-tasks.ts, bulk-admission.ts; services/persistence/data-job-uploads.ts; aws/logic/bulk-data-jobs.lambda.ts. controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CHG-007, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-PRV-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Run A File Job Through The Bulk Lane ## What It Does CRM file orchestration reads versioned input into chunks, plans batches and admits work within shared budgets. Workers use the ordinary receipt-protected batch runner, while durable task cursors support continuation. ## The Flow ```mermaid flowchart TD H1["CRM bulk submission"] --> H2 H2["CRM bulk submission"] --> H3 H3["Task function, chunkSource"] --> H4 H4["Task function, planBatches"] --> H5 H5["Task function, admitBatches"] --> H6 H6["CRM bulk worker"] --> H7 H7["Task function, settleIfDone"] ``` ## When Something Fails Malformed input, exhausted tasks or stalled admission can end the job after earlier work exists. File grouping checks do not prove whole-file atomicity across distant or resumed repetitions. Failure handlers and reconciliation settle execution, without reversing writes. ## Open Design Questions The recorded findings identify the remaining limits; this examination does not authorize stronger behavior or change the planning rules.