Asteria Fleet Data Quality Hub
Quick Start
Every Asteria Fleet audit follows the same skeleton:
- Read
environment_access.md for base_url and allowed_business_endpoints.
- Read the task's
case_scope.json for the collection ID, business cutoff, and scoped decision IDs.
- Discover: call
GET /api/catalog/collections and GET /api/catalog/schema to confirm the collection shape.
- Source snapshots: call
GET /api/source-snapshots to identify the authoritative (certified) snapshot and any provisional duplicates.
- Fetch data: use domain-specific endpoints or
POST /api/query with pagination.
- Reconcile: deduplicate (retain certified over provisional), quarantine invalid rows, detect mismatches.
- Normalize: apply unit conversions (
/api/reference/conversions) and FX (/api/reference/fx).
- Resolve focus entities: merge clusters, select survivors, compute canonical values.
- Assign control codes: derive opaque codes from data evidence (see control_codes.md).
- Certify: compute quality metrics, apply thresholds, return PASS/PASS_WITH_EXCEPTIONS/HOLD.
API Discovery
Use GET /api/catalog/collections to list available collections. Each object includes collection_id, snapshot_ids, and row_count. Use GET /api/catalog/schema to see field definitions for a collection. The schema endpoint accepts ?collection_id=... and returns field names, types, nullable flags, and primary-key markers.
GET /api/source-snapshots returns every snapshot across all collections. Filter by ?collection_id=... to get only relevant snapshots. Each snapshot has a snapshot_id and status field. Typical status values are CERTIFIED, PROVISIONAL, and STALE.
All domain endpoints support ?snapshot_id=... to scope to a single snapshot. Omitting the parameter returns the union. Use POST /api/query for SQL-like queries when you need filtering, aggregation, or joins beyond what the domain endpoints provide.
A full endpoint catalog is in api_endpoints.md.
Source Reconciliation (General)
Every audit resolves overlapping source records. The universal rule:
- Certified snapshots always take priority over provisional snapshots.
- When the same logical record appears in both, retain the certified occurrence and discard the provisional one.
- When a logical record appears only in a provisional snapshot, that occurrence is retained but may carry source-basis implications.
For contacts and maintenance events, logical identity is determined by the domain's natural key (person identity key for contacts, logical_event_id for maintenance events). For transactions (fuel and freight), logical identity is the transaction ID itself.
Snapshot status field: snapshots carry a status field. Read it from /api/source-snapshots. Values:
CERTIFIED: authoritative, always preferred
PROVISIONAL: secondary, retained only when no certified copy exists
STALE: treat as provisional for priority purposes
Count duplicate_raw_count as the number of raw rows that were discarded because a certified copy of the same logical record exists.
Domain-Specific Rules
Full quality rules per domain are in data_quality_rules.md. The summary:
Contacts (Partner Onboarding / Field Service)
- Cluster key: person identity key (UID or equivalent). Rows sharing the same identity key are the same person.
- Quarantine: a row with no usable email AND no usable phone. A usable email is non-empty and contains
@. A usable phone is non-empty, after stripping non-digits has length >= 7.
- Survivor: highest
row_id (lexicographic) in the cluster.
- Canonical city: from the Compliance Master source row in the cluster.
- Channel readiness: an entity is eligible when active AND has at least one usable email or phone. A channel is ready when consent is GRANTED.
- Field-level precedence for multi-source merges: name from HR Directory, contact (email/phone) from Identity Registry, depot (region) from HR Directory, consent from Identity Registry. When a source is absent for a given person, fall through Dispatch then HR Directory then Identity Registry.
Fuel Transactions
- Category matching: the
description field on each transaction is matched against /api/reference/aliases. Aliases map descriptive text to canonical fuel_type values (BIODIESEL, DIESEL, ELECTRIC_CHARGE, PREMIUM_UNLEADED, UNLEADED). A mismatch occurs when the expected_fuel_type on the transaction differs from the recognized canonical fuel type.
- Unrecognized: a description that matches zero aliases (no recognized category) or matches aliases that resolve to more than one distinct fuel type (ambiguous).
- Invalid quantity:
volume is zero, negative, or null.
- Normalization: apply
/api/reference/conversions (target unit L) then /api/reference/fx (target currency USD).
- Quarantine: transactions with an unrecognized description or invalid quantity. Do not include quarantined transactions in normalized totals.
Freight Charges
- Service class matching:
description field matched against /api/reference/aliases. Canonical service classes: EXPRESS, HAZMAT, OVERSIZE, REFRIGERATED, STANDARD. Mismatch when expected_service_class differs from recognized canonical class.
- Quarantine: ambiguous alias (matches >1 class), unrecognized alias (matches zero classes), non-positive
weight_kg, non-positive distance_km.
- Normalization: apply
/api/reference/conversions for weight (target KG) and distance (target KM), then /api/reference/fx for currency (target USD).
- Duplicate groups: when a
charge_id appears in both certified and provisional snapshots, report it as a duplicate group. Retain the certified occurrence.
Maintenance Events
- Duplicate resolution: by
logical_event_id across snapshots. Retain certified.
- Invalid events: missing or unparsable
event_timestamp, odometer_reading outside range (null, negative, or implausible), labor_hours negative or extreme. Invalid events are fully rejected from the corrected history.
- Odometer regression: within a single asset, when a later event (by timestamp) has a lower odometer reading than an earlier event. The later event is flagged as a regression. Regression events remain in the history for count purposes but their odometer reading is excluded from the corrected distance calculation.
- Corrected distance: for each asset,
last_reliable_odometer - first_reliable_odometer, excluding regressions, summed across all assets.
Control Code Assignment
Asteria uses opaque three-character codes for internal controls. The code schemes and assignment rules are documented in control_codes.md. Key families:
- IC (Identity): assigned based on identity resolution confidence and cluster characteristics.
- OR (Outreach): assigned based on contact readiness state.
- FP (Field Provenance): assigned based on source-system lineage of canonical field values.
- RB (Reference Basis): assigned for alias/fuel-reference decisions.
- SB (Source Basis): assigned for source-retention decisions per transaction.
- LD (Ledger Disposition): assigned for ledger routing per transaction.
- MS (Maintenance Source): assigned per maintenance event based on source snapshot.
- HR (History Route): assigned per maintenance event based on validation outcome.
Numeric Precision
All intermediate calculations use full precision. Round only at the final output to the precision specified in the answer template (typically 2 decimal places for monetary and physical measures, 4 decimal places for rates). Use standard rounding (half-up or half-even, either is acceptable as long as it is consistent).
Resources
api_endpoints.md
Complete endpoint catalog with parameters, pagination, and request/response shapes.
data_quality_rules.md
Domain-specific quality rules: quarantine conditions, deduplication, normalization, and survivor selection for each data domain.
control_codes.md
Opaque control code schemes and assignment rules for all eight code families used in Asteria Fleet audits.
1---2name: asteria-fleet-data-quality-hub-53description: "Data quality audit, reconciliation, and certification for the Asteria Fleet Data Quality Hub. Use when the task involves auditing, reconciling, normalizing, or certifying fleet operational data (contacts, fuel transactions, freight charges, or maintenance events) against a read-only Hub API, or when the task requires assigning Asteria opaque control codes (IC, OR, FP, RB, SB, LD, MS, HR) based on data evidence. Trigger on phrases like 'Fleet Data Quality Hub', 'Asteria fleet', 'partner onboarding certification', 'fuel ledger audit', 'freight accrual reconciliation', 'maintenance log integrity', 'field service roster readiness', 'contact-readiness brief', or any task referencing environment_access.md with Asteria API endpoints."4license: MIT5compatibility: designed for deepagents-code6metadata:7 source: https://skillmd.com/skills/prism-shadow/asteria-fleet-data-quality-hub-58---910# Asteria Fleet Data Quality Hub1112## Quick Start1314Every Asteria Fleet audit follows the same skeleton:15161. Read `environment_access.md` for `base_url` and `allowed_business_endpoints`.172. Read the task's `case_scope.json` for the collection ID, business cutoff, and scoped decision IDs.183. **Discover**: call `GET /api/catalog/collections` and `GET /api/catalog/schema` to confirm the collection shape.194. **Source snapshots**: call `GET /api/source-snapshots` to identify the authoritative (certified) snapshot and any provisional duplicates.205. **Fetch data**: use domain-specific endpoints or `POST /api/query` with pagination.216. **Reconcile**: deduplicate (retain certified over provisional), quarantine invalid rows, detect mismatches.227. **Normalize**: apply unit conversions (`/api/reference/conversions`) and FX (`/api/reference/fx`).238. **Resolve focus entities**: merge clusters, select survivors, compute canonical values.249. **Assign control codes**: derive opaque codes from data evidence (see [control_codes.md](references/control_codes.md)).2510. **Certify**: compute quality metrics, apply thresholds, return PASS/PASS_WITH_EXCEPTIONS/HOLD.2627## API Discovery2829Use `GET /api/catalog/collections` to list available collections. Each object includes `collection_id`, `snapshot_ids`, and `row_count`. Use `GET /api/catalog/schema` to see field definitions for a collection. The schema endpoint accepts `?collection_id=...` and returns field names, types, nullable flags, and primary-key markers.3031`GET /api/source-snapshots` returns every snapshot across all collections. Filter by `?collection_id=...` to get only relevant snapshots. Each snapshot has a `snapshot_id` and `status` field. Typical status values are `CERTIFIED`, `PROVISIONAL`, and `STALE`.3233All domain endpoints support `?snapshot_id=...` to scope to a single snapshot. Omitting the parameter returns the union. Use `POST /api/query` for SQL-like queries when you need filtering, aggregation, or joins beyond what the domain endpoints provide.3435A full endpoint catalog is in [api_endpoints.md](references/api_endpoints.md).3637## Source Reconciliation (General)3839Every audit resolves overlapping source records. The universal rule:4041- **Certified snapshots always take priority over provisional snapshots.**42- When the same logical record appears in both, retain the certified occurrence and discard the provisional one.43- When a logical record appears only in a provisional snapshot, that occurrence is retained but may carry source-basis implications.4445For contacts and maintenance events, logical identity is determined by the domain's natural key (person identity key for contacts, `logical_event_id` for maintenance events). For transactions (fuel and freight), logical identity is the transaction ID itself.4647**Snapshot status field**: snapshots carry a `status` field. Read it from `/api/source-snapshots`. Values:48- `CERTIFIED`: authoritative, always preferred49- `PROVISIONAL`: secondary, retained only when no certified copy exists50- `STALE`: treat as provisional for priority purposes5152Count `duplicate_raw_count` as the number of raw rows that were discarded because a certified copy of the same logical record exists.5354## Domain-Specific Rules5556Full quality rules per domain are in [data_quality_rules.md](references/data_quality_rules.md). The summary:5758### Contacts (Partner Onboarding / Field Service)59- **Cluster key**: person identity key (UID or equivalent). Rows sharing the same identity key are the same person.60- **Quarantine**: a row with no usable email AND no usable phone. A usable email is non-empty and contains `@`. A usable phone is non-empty, after stripping non-digits has length >= 7.61- **Survivor**: highest `row_id` (lexicographic) in the cluster.62- **Canonical city**: from the Compliance Master source row in the cluster.63- **Channel readiness**: an entity is eligible when active AND has at least one usable email or phone. A channel is ready when consent is GRANTED.64- **Field-level precedence for multi-source merges**: name from HR Directory, contact (email/phone) from Identity Registry, depot (region) from HR Directory, consent from Identity Registry. When a source is absent for a given person, fall through Dispatch then HR Directory then Identity Registry.6566### Fuel Transactions67- **Category matching**: the `description` field on each transaction is matched against `/api/reference/aliases`. Aliases map descriptive text to canonical `fuel_type` values (`BIODIESEL`, `DIESEL`, `ELECTRIC_CHARGE`, `PREMIUM_UNLEADED`, `UNLEADED`). A mismatch occurs when the `expected_fuel_type` on the transaction differs from the recognized canonical fuel type.68- **Unrecognized**: a description that matches zero aliases (no recognized category) or matches aliases that resolve to more than one distinct fuel type (ambiguous).69- **Invalid quantity**: `volume` is zero, negative, or null.70- **Normalization**: apply `/api/reference/conversions` (target unit `L`) then `/api/reference/fx` (target currency `USD`).71- **Quarantine**: transactions with an unrecognized description or invalid quantity. Do not include quarantined transactions in normalized totals.7273### Freight Charges74- **Service class matching**: `description` field matched against `/api/reference/aliases`. Canonical service classes: `EXPRESS`, `HAZMAT`, `OVERSIZE`, `REFRIGERATED`, `STANDARD`. Mismatch when `expected_service_class` differs from recognized canonical class.75- **Quarantine**: ambiguous alias (matches >1 class), unrecognized alias (matches zero classes), non-positive `weight_kg`, non-positive `distance_km`.76- **Normalization**: apply `/api/reference/conversions` for weight (target `KG`) and distance (target `KM`), then `/api/reference/fx` for currency (target `USD`).77- **Duplicate groups**: when a `charge_id` appears in both certified and provisional snapshots, report it as a duplicate group. Retain the certified occurrence.7879### Maintenance Events80- **Duplicate resolution**: by `logical_event_id` across snapshots. Retain certified.81- **Invalid events**: missing or unparsable `event_timestamp`, `odometer_reading` outside range (null, negative, or implausible), `labor_hours` negative or extreme. Invalid events are fully rejected from the corrected history.82- **Odometer regression**: within a single asset, when a later event (by timestamp) has a lower odometer reading than an earlier event. The later event is flagged as a regression. Regression events remain in the history for count purposes but their odometer reading is excluded from the corrected distance calculation.83- **Corrected distance**: for each asset, `last_reliable_odometer - first_reliable_odometer`, excluding regressions, summed across all assets.8485## Control Code Assignment8687Asteria uses opaque three-character codes for internal controls. The code schemes and assignment rules are documented in [control_codes.md](references/control_codes.md). Key families:8889- **IC** (Identity): assigned based on identity resolution confidence and cluster characteristics.90- **OR** (Outreach): assigned based on contact readiness state.91- **FP** (Field Provenance): assigned based on source-system lineage of canonical field values.92- **RB** (Reference Basis): assigned for alias/fuel-reference decisions.93- **SB** (Source Basis): assigned for source-retention decisions per transaction.94- **LD** (Ledger Disposition): assigned for ledger routing per transaction.95- **MS** (Maintenance Source): assigned per maintenance event based on source snapshot.96- **HR** (History Route): assigned per maintenance event based on validation outcome.9798## Numeric Precision99100All intermediate calculations use full precision. Round only at the final output to the precision specified in the answer template (typically 2 decimal places for monetary and physical measures, 4 decimal places for rates). Use standard rounding (half-up or half-even, either is acceptable as long as it is consistent).101102## Resources103104### [api_endpoints.md](references/api_endpoints.md)105Complete endpoint catalog with parameters, pagination, and request/response shapes.106107### [data_quality_rules.md](references/data_quality_rules.md)108Domain-specific quality rules: quarantine conditions, deduplication, normalization, and survivor selection for each data domain.109110### [control_codes.md](references/control_codes.md)111Opaque control code schemes and assignment rules for all eight code families used in Asteria Fleet audits.