# Deterministic integration workflows

Machine-readable workflows are published at `https://cleanedweb.com/arazzo.json`. OpenAPI
remains authoritative for individual operations.

## Exact count only

When the output is only "how many", run the `exactPropertyCount` workflow. It
resolves the maintained market and calls `countProperties` with the filters.
Do not call `searchProperties`, set a one-record limit, follow result cursors,
or download rich records just to derive the total. Require a non-negative
`total_matched` and a snapshot identity; the count consumes no delivery Units.

## Discover, search, validate, persist

Use this workflow only when the caller needs property records.

1. Fetch capabilities without using a cached marketing or coverage value.
2. Require a supported contract version and, for API-key or MCP access,
   `machine_access.enabled: true` plus non-empty `unit_costs`.
3. Fetch authenticated markets and require the requested market.
4. Resolve user-entered location text. If several candidates remain plausible, ask the user.
5. Create a unique idempotency key for the exact bounded request.
6. Submit `limit` and `max_units` with the search.
7. Apply every result-acceptance check before writing downstream.
8. Upsert by `property_entity_id`, retain `sources`, and store the usage receipt.

## True zero-result count or search

For count-only work, accept zero only when the exact count operation succeeded,
`total_matched` is zero, and the snapshot is present. For record retrieval,
accept an empty search only when HTTP succeeded, `returned` and `results.length`
are zero, `has_more` is false, `total_matched` is zero, the snapshot is present,
and the request was evaluated against an entitled ready market. Never convert
`401`, `403`, `429`, `503`, a network error, or a parsing error into empty success.

## Ambiguous location

Call location suggestions using the user's text. Present meaningful candidates and preserve
their `placeId`. Do not select a candidate merely because it is first. Resume the search with
both the original location text and the selected `location_place_id`.

## Idempotent recovery

After a timeout or retriable failure, resend the identical request with the identical key.
If the receipt reports `idempotentReplay: true`, continue using the recorded result and do not
perform the downstream business effect twice. A new key is allowed only for a genuinely new
request.

## Current property and history

Retrieve the canonical property by `property_entity_id`, then request its newest-first changes
with a limit from 1 through 200. Finalized change history excludes suspected transitions and
incomplete observer runs. Re-read the property endpoint when current state matters.

## Webhook processing

1. Read the exact raw bytes.
2. Verify timestamp and every supported `v1` signature in constant time.
3. Claim `webhook-id` durably before the business effect.
4. Parse and validate `property-event-v1`.
5. Commit the effect and event claim in one transaction where possible.
6. Return `2xx`; for a duplicate committed ID, acknowledge without repeating the effect.

## Agent stop conditions

Stop or request human input for unsupported major versions, unsupported or unentitled markets,
ambiguous locations, duplicate canonical IDs, count mismatches, stale snapshots, unexpected
truncation, insufficient Units, a raised Unit ceiling, revoked authentication, or an unknown
error code.