Asteria Fleet Data Quality
Workflow
- Read the task prompt,
payloads/case_scope.json, andpayloads/answer_template.json. Treat the template as the output contract: required keys, exact names, enum values, precision, and ordering rules override intuition. - Read runtime access details from
environment_access.md. Use only the listed endpoints. Do not invent data or use prior task answers. - Fetch the catalog, schema, source snapshots, and all rows for the scoped
collection_id. The REST endpoints usecollectionfor collection filters,domainfor aliases,kindfor unit conversions, andcurrencyfor FX. They page withlimitandoffset. - Prefer row-level calculations over shortcut inference. Reconcile duplicates, classify exceptions, compute totals, then fill the decision-code panels from the same evidence.
- Return only the final JSON object. Before finalizing, check every array is sorted as specified, every count is internally consistent, and every rounded number uses the contract precision.
Use scripts/fetch_hub_bundle.py to collect a complete local JSON bundle for a scoped collection:
python skill/scripts/fetch_hub_bundle.py \
--base-url "$TASK_ENV_BASE_URL" \
--family fuel \
--collection "$COLLECTION_ID" \
--out /tmp/asteria-bundle.json
Families are contacts, fuel, freight, and maintenance.
Shared Reconciliation
- Scope rows by the case dates: collection ID, cutoff/as-of timestamp, and any business-period bounds. Use source snapshots to identify the authoritative retained source, normally a
CERTIFIEDsnapshot when one exists; otherwise retain the best available non-final snapshot. - For duplicated logical records, group by the public stable ID: contact row clusters by normalized identity/contact evidence, fuel by
transaction_id, freight bycharge_id, and maintenance byevent_id. Count raw rows before retention and logical records after retention. - For duplicate groups in transactional and maintenance tasks, retain the authoritative snapshot occurrence; report all snapshot IDs lexicographically where the contract asks for them.
- Match aliases by normalized, case-insensitive containment of
alias_textin the description field. Use only reference rows effective on the business date or cutoff and with an eligible active status. Zero matching canonical values is unrecognized; more than one matching canonical value is ambiguous. - Convert units with
/api/reference/conversions: fuel volume to liters, freight weight to kilograms, freight/maintenance distance to kilometers. Convert money with/api/reference/fx, preferringCERTIFIEDrates for the business date and treating USD as factor 1. - Round only at the final contract field: usually 2 decimals for normalized quantities and spend, 4 decimals for rates, and exact integers for counts.
Decision Codes
Apply compact codes by condition, not by ID.
- Reference rows:
RB-42active and effective for the scoped date;RB-17inactive, retired, future-effective, or otherwise not effective for the date;RB-83provisional/non-final reference evidence. - Fuel/freight source basis:
SB-24single authoritative/certified retained occurrence;SB-61duplicate logical record retained from the authoritative/certified occurrence;SB-79single non-authoritative/provisional retained occurrence. - Fuel/freight ledger disposition:
LD-72valid recognized class/type matches expected;LD-31valid recognized class/type differs from expected;LD-14no recognized alias;LD-88multiple recognized canonical aliases;LD-53invalid physical measure such as nonpositive quantity, weight, or distance. - Maintenance source:
MS-12single authoritative/certified event;MS-47duplicate event retained from authoritative/certified;MS-86single provisional/non-authoritative event. - Maintenance history route:
HR-33accepted into corrected history;HR-19sequence-only odometer regression excluded from corrected history;HR-74rejected for missing/unparsable timestamp, invalid odometer, negative labor, or extreme labor. - Contact identity:
IC-70clean automerged duplicate person;IC-25shared usable identifier/channel that does not justify a merge;IC-90contested identity/watchlist cluster with unresolved same-name or identifier conflict;IC-40no usable-contact identity quarantine. - Contact outreach:
OR-35active, usable channel, consent granted;OR-80active and usable channel but consent not granted;OR-60no usable email or phone;OR-15inactive exclusion. - Contact field provenance:
FP-55field-level precedence applied across merged source rows;FP-20single-source or no field conflict;FP-75quarantined/no usable-contact record.
Contacts
- Normalize email with Unicode NFKC, strip, and lowercase. Normalize phone to digits only. Normalize names with Unicode NFKC, trimmed whitespace, collapsed internal spaces, and casefolding for comparison; preserve display Unicode in canonical names.
- Automerge rows only when strong contact evidence links compatible identities, such as the same normalized email or phone with compatible names. Do not automerge rows that have no usable email or phone. Treat shared channels or hints across different names as contested/shared-channel evidence, not as an automatic merge.
- Prefer source-specific field precedence over whole-row precedence. Identity/compliance sources usually win master ID, contact, consent, and onboarding city fields; HR/depot sources usually win name and depot/region fields for roster tasks. Fall back to verified rows, rows with
master_hint, latestbusiness_updated_at, then stable row ID. - A canonical person is dispatchable/channel-ready only when active, has at least one usable email or phone, and consent is
GRANTED. Partition readiness counts so dispatchable/consent-blocked/no-contact/inactive buckets sum to the canonical population requested by the template. - For focus rows, find the canonical cluster containing the anchored row, list all member row IDs sorted lexicographically, choose the same master/survivor used by the cluster, and report canonical fields from the selected field-level sources.
- Certification/release decisions come from the case thresholds when present. Without explicit thresholds, hold when contested identifiers or required dispatch/contact blockers remain; otherwise pass or pass with exceptions according to the prompt's action map.
Fuel And Freight
- Retain one row per logical transaction/charge before all exception and total calculations. Duplicates contribute to raw and duplicate counts, not normalized totals.
- Fuel valid records require positive quantity and exactly one recognized fuel type. Freight valid records require positive weight, positive distance, and exactly one recognized service class.
- Mismatches are valid retained records whose recognized fuel type or service class differs from the expected field. Quarantines are invalid measure, unrecognized alias, or ambiguous alias records. Quarantined records do not enter normalized totals; valid mismatches do.
- Build exception lists from distinct retained logical IDs. Sort ID lists lexicographically. Rank merchants/carriers by the template's metric and tie breakers; carrier mismatch exposure is normalized USD spend on valid mismatches only.
Maintenance
- Use source snapshots to identify the authoritative snapshot and row count. Duplicate groups are all event IDs appearing in more than one snapshot.
- Reject retained events with missing/unparsable event time, invalid odometer, negative labor, or extreme labor. Treat very large labor values as extreme when they are outside a plausible single-event range.
- Convert odometer readings to kilometers before sequence checks. For each asset, sort retained, non-rejected Q1 events by event time and stable event ID. A reading lower than the prior reliable reading is an odometer regression: report it separately and exclude it from corrected history metrics.
- Corrected distance is the sum across assets of last reliable odometer minus first reliable odometer after rejected and regression events are excluded.