lifecycle · identity

Stable identity. Explicit outcomes.

Listing identity, display references, controlled indexes and internal property IDs solve different problems and must never be conflated.

Four identity contracts

provider_id + listing_id

The only external identity. It is stable, provider-scoped, unique in each feed and never reused for another home.

reference

An agency-facing label that may change and is not required to be globally unique.

controlled IDs

Real zentra database IDs for location, currency, property type and feature values. Labels are diagnostic.

properties.id

Assigned after import. Providers must not send it and importers must not infer it.

Fetch
Download with bounded timeout, size and TLS policy. Persist a non-secret fingerprint.
Validate
Reject malformed, schema-invalid or hierarchy-invalid data before any persistence.
Upsert
Resolve by provider/feed + `listing_id`; changed `updated_at` and content update the canonical DTO.
Reconcile
Missing IDs become withdrawal candidates. Guardrails stop unexpected mass deletion.
Publish
Only the successfully validated snapshot becomes active; image jobs remain idempotent.

Status	Visible?	Importer action
available / reserved / under_offer	yes when `visible=true`	upsert and publish intent
sold / rented	policy-driven	retain outcome; stop active marketing
withdrawn	no	archive immediately under provider policy
draft	no	retain for diagnostics; never publish