docs operator registry runs - AlexandreZanata/Abastevo GitHub Wiki
Scope: national registry staging/reconciliation jobs. Staging is operator-triggered until live source access is verified; the daily reconcile schedule is disabled for the same reason. Publication is append-only with no pointer to roll back.
-
registry-reconcile-daily(registry-reconcilev1, every 24 h): disabled — reasonP25 pending: no live source access yet. Enable only after T02-style live source reconfirmation plus a successful operator-triggered staging of the same snapshot shape. - Daily CSV reconciliation stays the target cadence (B-BR-D12); targeted API lookups run on demand for reported/changed CNPJs.
-
Stage a snapshot (operator step, local secrets only): fetch the
approved CSV/API origin per
docs/product/REGISTRY_SOURCES.md, then stage with the boundedregistry.StageCSV/Discoverentry points (100 MB / 500k rows / page-100 caps). Never hand-editregistry_assertions; neverTRUNCATE. -
Reconcile: enqueue
registry-reconcilev1{source, snapshot}(dedupe keyregistry-reconcile:<source>: <snapshot>converges duplicates) or run the worker with the schedule enabled. Onlycompleteruns publish; anything else is refused byReconcileRun. - Pause: keep the schedule disabled (default) or redeploy with the entry disabled; in-flight runs finish their batch and report — nothing half-publishes. Resume by re-enqueueing the snapshot (replay is idempotent).
- Retry: failed jobs retry with backoff to the cap via the platform dispatcher, then park as dead; replay dead or re-enqueue the same snapshot after fixing the cause. Stale leases expire and are fenced by token (a dead worker never double-publishes: the assertion key converges).
-
Quarantine: inspect
registry_source_runs(quarantined+error_code+ counts); fix the source/layout and stage a new snapshot. Last-good catalog stays served throughout (D05). -
Last success / freshness:
LastCompleteRegistryRun(source)(snapshot, finished_at, counts). Alert when age exceeds 24 h past the daily target or the 48 h escalation threshold (B-BR-D12 objective, measured from sufficient evidence, not inauguration). - Rollback: no publication pointer exists by design. Revocation sticks via status; wrong projections are corrected by new audited revisions, never deletes. Disable the source flow to stop further publication.
| symptom | cause | action |
|---|---|---|
run failed/oversize, row_cap
|
snapshot exceeds caps | split scope or recalibrate [CALIBRATE] budgets with measured data |
run quarantined/missing_columns, unknown_columns
|
layout drift | freeze new header mapping in policy; new snapshot |
run failed/truncated, transport, provider_error
|
source/outage | retry after cause fixed; last good preserved |
run quarantined/page_quota, request_quota
|
traversal quota hit | raise quota deliberately or accept partial explicitly (never complete) |
| job dead after retries | persistent failure | inspect last_error, fix, replay dead |
| complete runs age > 48 h | missed source/operator | escalate with cause/status (B-BR-D12), do not redefine eligibility |