Landlord API — Slice 2: Idempotent Sync
Slice 1 made a landlord's API key a valid identity; nothing yet stopped a nightly sync writing the same flat twice. Slice 2 makes every write repeatable through per-source external refs, an address fingerprint that refuses to guess, a single-transaction idempotency claim, and a test-mode sandbox that never touches the public marketplace. Twenty-five decisions (D12–D36), each with its rejected alternatives recorded.
- Predecessor Slice 1 — Foundation (2026-09-19), merged in 8942b456 (PR #139)
- ADRs 0002
- Status Approved
Why this slice exists
Slice 1 made a landlord's API key a valid identity. Nothing yet stopped a sync job writing the same flat twice, so a nightly run would fill the marketplace with copies of one property. Slice 2 makes every write repeatable: the same sync, run a hundred times, leaves one property and one listing.
The matching pipeline
One entry point decides whether an incoming property is new or already known. Each step is tried in order, and the first hit wins.
owner_user_id and
same is_test — and neither scope is optional.
| Step | Try | Result | Audit action |
|---|---|---|---|
| 0 | Idempotency-Key seen before | replay, stop | — |
| 1 | source + external_ref in the refs table | 200, that property | update |
| 2 | address fingerprint, when computable | 200, adopt | adopt |
| 3 | nothing matched | 201, new property | create |
D26 · Who runs the pipeline?
Only the API, through a new PropertyUseCase.Sync. The panel
always creates a new row — but still computes and stores the fingerprint.
Adoption means "this is the same flat under another name", which only makes sense when a ref explains it afterwards. A human clicking Add property means "make a new one". If the panel ran step 2 it would find the landlord's existing flat and return the old id with a 200 — the landlord believes they created a flat and has instead edited one, with nothing on screen to explain it.
Rejected: a boolean flag on Create (one function with two
behaviours, and the existing tests would guard the wrong path); letting the
panel adopt too (D33 stops hand-made duplicates instead).
D24 · What may a matched write overwrite?
A matched write patches — an absent key leaves the field
unchanged. Only a new property takes a full replace. The panel's
PUT is untouched.
PropertyUseCase.Update is PUT semantics: absent optional
fields reset to zero (property.go:159). Applied to a matched
write, that silently deletes the landlord's own work.
Rejected: honest PUT-replace requiring feeds to send complete records — silent data loss is then one missing field away, and most feeds send a subset.
What a source is (D22)
source is the namespace for refs. It decides whether two sync
jobs share one ref or keep separate ones, so it has to be an identifier, not
prose.
- Shape
^[a-z0-9][a-z0-9_-]{0,31}$— 1 to 32 characters- Normalize
- lowercase before storing and before lookup
- Pairing
- all-or-nothing with
external_ref; one without the other is a400 - Panel write
- sends neither, writes no ref row
The normalizer (D19)
Lowercase, strip punctuation, collapse whitespace, then expand the common Malaysian road-type abbreviations. No fuzzy matching, no similarity threshold — a match is always explainable.
jln -> jalan lrg -> lorong
tmn -> taman bdr -> bandar
kg -> kampung psn -> persiaran
blok -> block no. -> (dropped)
fingerprint = sha256(
norm(building_name or address_line)
+ '|' + norm(unit_number)
+ '|' + postcode )
Unit forms normalize too: #12-3, Unit 12-3 and
12 - 3 all become 12-3. A landed property has no
unit by nature, so an empty unit is legitimate there and the fingerprint is
still computed. Only a high-rise missing its unit yields NULL.
Four ways the sync refuses instead of guessing
D18 states the principle — guessing is worse than missing — and four decisions apply it. Each returns a 409 that names the real problem, rather than writing something plausible.
-
ambiguous_matchstep 2 finds 2+ candidates for one landlordD27 409 -
unit_number_requiredsame building + postcode, unit missing on either sideD29 409 -
duplicate_addressunique (owner_user_id, is_test, address_fingerprint)D33 409 -
listing_not_reopenableevery listing on the property is terminalD21 409
D33 · One address per landlord, held by the database
A partial unique index on
(owner_user_id, is_test, address_fingerprint), replacing the
plain lookup index.
A write must recompute the fingerprint, or a property that changes address
keeps hashing the old one forever. But recomputing lets one bad
PUT give two rows the same fingerprint, and step 2 would then
fire 409 ambiguous_match every night until a human noticed.
Same owner, same building, same unit, same postcode is the same
flat — a real invariant, so the database holds it rather than the
application.
Rejected: an advisory fingerprint with application-side collision checks — a bad PUT then wedges a landlord's sync until someone investigates.
D21 · A sync never re-lists a flat
When every listing on a property is terminal, the API upsert returns
409 listing_not_reopenable and touches nothing.
uq_rental_listings_active_property only covers
draft, pending_review and live. A
rented row leaves the property with no active listing, so a
naive upsert would create a fresh draft every night — re-listing an
occupied flat, or undoing an admin rejection. Without a listing ref the
sync cannot tell a stale replay of the old offer from a deliberate new
letting.
Rejected: allowing re-creation from withdrawn only —
withdrawn is no clearer than rented on that
point. The panel rule is untouched: entity.AllowsNewListing
(listing.go:140) still lets a human re-let.
Idempotency: one transaction, no bookkeeping
Recording the key after the work loses the race. A hung request retried with the same key runs twice: both look up the key, both miss, both create. Either two properties exist, or the unique index fires and one caller gets a 500.
-
Claim, then work — in one BEGIN
INSERT INTO rental_idempotency (…)withresource_idstill NULL, then the resolution pipeline, then anUPDATEfillingresource_idandstatus_codebeforeCOMMIT. -
A different fingerprint is a conflict
Same key, different canonical body →
409 idempotency_conflict, decided on the re-read after the unique violation. -
The body is hashed canonically, not byte-for-byte
Decode into
any, re-encode, hash that.encoding/jsonsorts map keys, so canonical form costs three lines. Otherwise an honest retry that reorders JSON keys would get a 409 and stop the sync. -
A purged resource re-runs rather than 404s
SELECT … FOR UPDATE, delete the stale row, re-insert a fresh claim and run the pipeline — all inside the same transaction, so concurrent replays stay serialized.
What catches a blind retry on each of the ten routes
| Write | What catches it |
|---|---|
POST /properties | ref (step 1), fingerprint (step 2), else the unique index (D33) → 409 duplicate_address, or 409 unit_number_required (D29) |
PUT /properties/:id | explicit id; merge semantics (D24) make a repeat a no-op |
POST /listings | the active-listing rule updates in place; terminal refuses (D21) |
PUT /listings/:id | explicit id; identical data changes no state |
POST /listings/:id/submit | the state machine — already pending_review → 409 |
POST /listings/:id/withdraw | the state machine |
Test mode: a real sandbox, invisible to renters
Slice 1's BlockTestKeyWrites() made test keys read-only. It is
removed here and replaced by row marking: is_test is taken from
key_mode at creation, and a listing inherits it from its
property.
Public marketplace
hidden- One line in
publicScopeaddsl.is_test = FALSE - Protects
PublicSearch,PublicGetBySlug,PublicAreas,PublicPropertyTypes - An integration test walks every public read path
Admin review queue
hidden- Humans never spend time approving fake flats
- Which is why test submits self-approve (D32)
The landlord's own list
visible- Badged "test" in the panel
- Otherwise the sandbox is useless to them
D32 · pending_review does not rest in test mode
Any transition landing in pending_review continues to
live in the same transaction — covering both
Submit and the rent demotion.
Two doors lead into pending_review, and
listingTransitions offers no way out of either without an
admin. A rent change is the door a sync walks through every night,
so fixing only Submit would leave the sandbox dead at step
two. The safety rail already exists: publicScope filters
is_test = FALSE, so a live test listing is still invisible
everywhere public.
Rejected: a separate admin queue tab for test rows (humans approving fake flats); a test-only approve route (breaks Slice 1's frozen ten-route contract); leaving the sandbox stuck (the spec would keep promising a rehearsal that does not exist).
Purge (D28)
A sweep hard-deletes test properties after 30 days with no writes — aged by
updated_at, not created_at, because a sandbox that
syncs nightly for two months is in daily use.
-
Select candidates
is_test,updated_at < now() - 30 days, and no tenancy reachable from any of the property's listings. -
Delete each one in its own transaction
CASCADE clears photos, proofs, listings, refs and flags.
-
A failure logs and the loop continues
One bad row costs one row, not the whole sweep.
Cross-landlord duplicate flags
At property create or adopt, when the fingerprint matches a property owned by someone else, a flag is raised. Creation is never blocked. Test rows never raise flags — they are not real properties.
D25 · The publication hold is decided at submit time
Nothing is stored. The flag records the pair, and Submit
checks every open flag where this property sits on either
side, reading current verified proofs.
A boolean frozen at flag time records who happened to be verified
that day. Proof verification is an admin action on its own schedule, and
the flag row is directional — so a check reading only the newcomer's side
would let two claimants both go live purely on ordering. Reusing
ProofRepo.CountByProperty, which Submit already
calls, costs one extra call of a shape already there.
Rejected: keeping the stored blocks_publication boolean — the
hold would then depend on verification timing rather than on the facts at
submit.
| Situation | Outcome |
|---|---|
| Neither side has verified proof | both publish, the flag is advisory |
| Only the other side has proof | I wait — 409 duplicate_under_review |
| Only I have proof | the other side waits |
| Both have proof | both wait — a real dispute for an admin |
An admin resolves a flag as cleared (the listing may proceed) or
upheld (rejected or suspended). The review queue row gains an
API badge when origin_channel = 'api' and a
duplicate warning when an open flag exists on either side.
Schema
Changed columns
rental_properties gains six columns;
rental_listings gains the same four origin and test columns.
Every one has a default, so no existing row or caller breaks.
| Column | Type | Why |
|---|---|---|
unit_number | TEXT NOT NULL DEFAULT '' | D18 — the fingerprint input that did not exist |
address_fingerprint | TEXT nullable | NULL means not confident, never matched |
is_test | BOOLEAN NOT NULL DEFAULT FALSE | D16 |
origin_channel | TEXT NOT NULL DEFAULT 'panel' | panel | api | cli (D34) |
origin_key_id, origin_key_name | TEXT | which key created it |
New · rental_property_external_refs
CREATE TABLE rental_property_external_refs (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
property_id UUID NOT NULL REFERENCES rental_properties(id) ON DELETE CASCADE,
owner_user_id TEXT NOT NULL,
source TEXT NOT NULL,
external_ref TEXT NOT NULL,
is_test BOOLEAN NOT NULL DEFAULT FALSE,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE UNIQUE INDEX uq_property_refs
ON rental_property_external_refs (owner_user_id, source, external_ref, is_test);
CREATE INDEX idx_property_refs_property
ON rental_property_external_refs (property_id);
owner_user_id is copied in rather than joined: lookups are
always scoped to the caller, and the rule is "unique for this landlord",
which a join cannot enforce. is_test is in the unique index on
purpose — a landlord testing the exact payload they will later send live must
be able to reuse the same external_ref in both modes.
New · rental_idempotency
CREATE TABLE rental_idempotency (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
api_key_id TEXT NOT NULL,
idempotency_key TEXT NOT NULL,
request_fingerprint TEXT NOT NULL, -- sha256(method|path|canonical(body))
resource_type TEXT NOT NULL,
resource_id TEXT, -- filled before commit, once the outcome is known
status_code INT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE UNIQUE INDEX uq_idempotency ON rental_idempotency (api_key_id, idempotency_key);
CREATE INDEX idx_idempotency_sweep ON rental_idempotency (created_at);
Rows are swept after 24 hours. Storing the outcome id rather than the
response body (D15) means a replay never serves stale content, and no
response bodies are kept. All ten v1 routes require
APIKeyAuthMiddleware, so api_key_id is always
present — panel writes never reach this table.
New · rental_duplicate_flags
CREATE TABLE rental_duplicate_flags (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
property_id UUID NOT NULL REFERENCES rental_properties(id) ON DELETE CASCADE,
matched_property_id UUID NOT NULL REFERENCES rental_properties(id) ON DELETE CASCADE,
fingerprint TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'open'
CHECK (status IN ('open','cleared','upheld')),
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
resolved_at TIMESTAMPTZ,
resolved_by_user_id TEXT,
resolution_note TEXT
);
CREATE INDEX idx_dup_flags_open
ON rental_duplicate_flags (property_id) WHERE status = 'open';
CREATE INDEX idx_dup_flags_open_matched
ON rental_duplicate_flags (matched_property_id) WHERE status = 'open';
Indexes for matching
-- step 2, same landlord — unique, not just an index (D33)
CREATE UNIQUE INDEX uq_props_fingerprint_owner
ON rental_properties (owner_user_id, is_test, address_fingerprint)
WHERE address_fingerprint IS NOT NULL AND deleted_at IS NULL;
-- cross-landlord flagging
CREATE INDEX idx_props_fingerprint_global
ON rental_properties (address_fingerprint)
WHERE address_fingerprint IS NOT NULL AND deleted_at IS NULL;
-- keep test rows off the public path cheaply
CREATE INDEX idx_listings_public
ON rental_listings (status) WHERE is_test = FALSE;
Contract changes
Property create and update accept three new optional fields. A panel call sends none of them and behaves exactly as today.
{ "source": "propertyguru",
"external_ref": "PG-88213",
"unit_number": "12-3",
"address_line": "...", ... }
Responses add unit_number, origin_channel,
is_test, and external_refs as a list of
{source, external_ref}.
PUT /properties/:id names the property explicitly, so it
never matches — it records the ref against that id and
nothing else.
The one behaviour change to document loudly
| Case | Before | Now |
|---|---|---|
| POST, new | 201 | 201 |
| POST, ref or fingerprint matched | 201, a duplicate | 200 |
| POST, replayed idempotency key | 201, a duplicate | 200 with Idempotent-Replay: true |
New error codes
Appended to the frozen table from Slice 1 §8.2. All are 409.
idempotency_conflict- same key, different canonical body
duplicate_under_review- an open cross-landlord flag, other side has verified proof
listing_not_reopenable- every listing on the property is terminal (D21)
ambiguous_match- step 2 found 2+ candidates (D27)
unit_number_required- weak match on a unit-less high-rise (D29)
duplicate_address- the fingerprint is taken for this landlord (D33)
duplicate_external_ref- the ref is bound to another property of this landlord
All decisions, and what each turned down
Slice 1's numbering continues. D17 is superseded by D25. D20 was dropped
outright — uq_rental_listings_active_property already identifies
a listing, so a listing ref would be a second name for the same thing.
D12–D36 · the full decision table
| # | Decision | Chosen |
|---|---|---|
| D12 | Repeat POST with a known external_ref | Update in place, return 200 |
| D13 | Fingerprint hit on the same landlord's property | Always adopt |
| D14 | Ref storage | One ref per source, in a side table |
| D15 | Idempotency records | Postgres, store the outcome id, replay re-reads |
| D16 | Test rows | is_test column, filtered in the repository layer |
| D17 | Publication hold | Superseded by D25 |
| D18 | Fingerprint inputs | Add unit_number; no fingerprint when not confident |
| D19 | Normalizer | Conservative plus Malaysian abbreviations |
| D20 | Listing external refs | Dropped. A listing's identity is its property's |
| D21 | Sync upsert when every listing is terminal | Refuse: 409 listing_not_reopenable. Panel unchanged |
| D22 | Who defines source | Client-declared, validated identifier. No enum, not key-derived |
| D23 | Idempotency write order | One transaction. The unique INSERT itself blocks racers |
| D24 | What a matched write may overwrite | Merge: absent key leaves the field unchanged |
| D25 | The publication hold | Evaluated live at Submit, on both sides |
| D26 | Who runs the pipeline | API only, via PropertyUseCase.Sync |
| D27 | Step 2 finds two or more candidates | 409 ambiguous_match, no mutation |
| D28 | Test-row purge | One transaction per property, age by updated_at |
| D29 | High-rise with no unit on either side | Weak match: 409 unit_number_required, never adopt |
| D30 | Existing rows | Backfill fingerprints for landed properties only |
| D31 | Replay hashing and stale outcomes | Canonical JSON; a missing resource re-runs in the same transaction |
| D32 | Test mode and pending_review | Never a resting state; it continues to live |
| D33 | One address per landlord | Partial unique index; 409 duplicate_address |
| D34 | Naming | origin_source → origin_channel |
| D35 | Audit of an adoption | A distinct adopt action. No new table, no UI |
| D36 | Idempotency-Key | Optional. It buys clean replays, not duplicate prevention |
Rejected alternatives · recorded so nobody re-proposes them
| # | Rejected | Why |
|---|---|---|
| D21 | Allow re-creation from withdrawn only | Without a listing ref the API cannot tell a stale replay from a deliberate new letting |
| D22 | A fixed enum of source names | Product policy, and none exists in the repository |
| D22 | Derive source from api_key_id | Key rotation would orphan every ref and the next sync would rebuild the set as duplicates |
| D23 | Record the key after the work succeeds | Loses the race: two requests both miss, both create |
| D23 | Separate reservation transaction with in_progress, expiry and takeover | A status column, an expiry rule and a sweep, for a case plain rollback already handles |
| D24 | Honest PUT-replace, requiring complete records | Silent data loss is one missing field away, and most feeds send a subset |
| D25 | Keep the stored blocks_publication boolean | The hold would depend on who happened to be verified the day the flag was born |
| D26 | A boolean flag on Create | One function with two behaviours; existing tests would guard the wrong path |
| D26 | Let the panel adopt too | A human clicking Add would silently edit an old row. D33 stops hand-made duplicates instead |
| D27 | Pick the oldest candidate | A guess between two identical rows. D18 says guessing is worse than missing |
| D28 | One batched DELETE with a NOT EXISTS guard | An unexpected RESTRICT still aborts the whole sweep, then fails every night, silently |
| D29 | Relax D18, fingerprint high-rises on building + postcode alone | Reopens the overwrite hole D18 exists to close |
| D30 | Backfill condos by parsing the unit out of address_line | Free-text parsing is the fuzzy matching this design forbids |
| D31 | Keep the byte-exact body hash | An honest retry that reorders JSON keys would get 409 and stop the sync |
| D31 | Return 410 Gone when the resource is purged | Correct in theory, useless to an unattended sync with no human to read it |
| D32 | Show test rows to admins in a separate queue tab | Real people spending time approving fake flats |
| D32 | Add a test-only approve route | Breaks Slice 1's frozen ten-route contract for one rehearsal step |
| D32 | Leave the sandbox stuck, scope it to writes only | The spec would keep promising a rehearsal that does not exist |
| D33 | Keep the fingerprint advisory, check collisions in app code | One bad PUT then wedges a landlord's sync every night until someone investigates |
| D34 | Keep origin_source and document the difference | Two fields called "source" in one JSON object stay confusing forever |
| D35 | Rely on update plus actor_type = api_key | Proves a key wrote the row, not that a match happened — and the match is what can go wrong |
| D36 | Require Idempotency-Key on every write | Buys no correctness once D33 exists, and breaks casual curl use |
Evidence the decisions rest on
Read from the repository on 2026-09-22. Each row is a fact a decision above depends on — several contradicted the spec's first draft.
| Fact | Evidence | Used by |
|---|---|---|
The active-listing unique index covers draft, pending_review, live only — four statuses are unguarded | migrator_rental.go:180-182 | D21 |
AllowsNewListing lets a human re-list once only terminal rows remain | listing.go:140 | D21 |
All ten v1 routes require APIKeyAuthMiddleware, so api_key_id is always set | v1_routes.go:44-72 | D23 |
PropertyUseCase.Update is full-replace, and an address change forces review | property.go:159-183 | D24 |
Submit already calls CountByProperty, which counts verified, live proofs | listing.go, ports.go:154-159 | D25 |
listingTransitions offers no EventSubmit out of pending_review | listing.go | D32 |
| Two RESTRICT edges sit below a property: payment records and handover reports | migrator_rental.go:619, :829 | D28 |
The audit action column is plain TEXT NOT NULL, no CHECK | migrator.go:2864 | D35 |
The request context carries api_key_id, api_key_name, actor_type, key_mode — but no source concept | api_key_auth_middleware.go:152-156 | D22, D34 |
Foundations reused, not rebuilt
- One active listing per property
- a unique partial index already enforces it, so listings need no ref
publicScope(ctx)- a single choke point for all public reads — a one-line test-row filter
ProofRepo.CountByProperty- already counts verified proofs; the publication hold introduces no new concept
- Cross-landlord rows read as 404
application.EnsureOwner's rule; mode isolation follows it exactly- ADR-0002 audit triggers
- keep their rows even after a hard test-row delete
Tasks
Tasks 4–8 are the spine. Tasks 9–12b are the sandbox and the replay path. Tasks 13–15 are the fraud guard. Task 16 is the only frontend work.
All 21 tasks with their verification method
| # | Task | Verify |
|---|---|---|
| 1 | Re-record the rental test baseline | numbers written down |
| 2 | Migration: property and listing columns, landed fingerprint backfill (D30) | migration test |
| 3 | Migration: refs, idempotency, flags tables, unique fingerprint index (D33) | migration test |
| 4 | unit_number on PropertyInput, entity, repository | unit |
| 5 | Address normalizer and ComputeAddressFingerprint | unit |
| 6 | Refs repository, source validation (D22) and lookup | unit |
| 7 | Resolution pipeline in a new PropertyUseCase.Sync (D26, D27, D29), merge on match (D24), adopt audit action (D35) | unit |
| 8 | Listing upsert via the active-listing rule, terminal refusal (D21) | unit |
| 9 | Idempotency claim in the write transaction (D23) and sweep | unit, integration |
| 9b | Test-row purge, per-property transactions (D28) | integration |
| 9c | origin_source → origin_channel rename, drop top-level source (D34) | golden |
| 10 | is_test propagation and mode isolation | unit |
| 11 | publicScope and admin queue filters | integration |
| 12 | Remove BlockTestKeyWrites; pending_review continues to live in test mode (D32) | integration |
| 12b | Canonical-JSON fingerprint and stale-replay re-run (D31) | unit, integration |
| 13 | Duplicate flag creation (pair only, no stored decision) | unit |
| 14 | Submit live hold check on both sides (D25) | integration |
| 15 | Admin resolve endpoint and queue badges | integration |
| 16 | Panel: unit field with a prompt on any high-rise missing one, test badge, duplicate warning | render tests |
| 17 | rental-v1.yaml and golden re-pin; document Idempotency-Key as replay ergonomics (D36) | golden |
| 18 | End-to-end two-source sync | integration |
Testing expectations
Fifty-one tests across unit, integration, migration and golden. Integration
tests follow the existing recipe: pg-test on :55432, migrations
run from a directory with no .env, because
backend/go/.env points at UAT.
| What | Kind | Fails when |
|---|---|---|
| Normalizer | unit, table-driven | Jln and Jalan produce different hashes |
| NULL fingerprint without a unit | unit | a high-rise with no unit gets a hash |
| Resolution order | unit | the fingerprint runs before the ref lookup |
| Concurrent same-key requests (D23) | integration | two properties appear, or one caller gets a 500 |
| Rolled-back write frees the key (D23) | integration | a failed write blocks the same key forever |
| Key order does not change the fingerprint (D31) | unit | a reordered retry returns 409 |
| Replay after the resource is purged (D31) | integration | a successful request replays as 404 |
| Merge on match keeps panel data (D24) | integration | adoption wipes amenities, building name or size |
| Panel create never adopts (D26) | unit | a panel create returns an existing property id |
| Two candidates refuse (D27) | unit | one is picked, or a third row is created |
| Weak match refuses, never adopts (D29) | unit | a unit-less condo is adopted or duplicated |
| Backfill skips colliding fingerprints (D33) | migration | the unique index fails to build on real data |
| Terminal listing is not re-created (D21) | integration | a rented property gets a new draft from the sync |
Test rent change returns to live (D32) | integration | the sandbox dead-ends after one demotion |
| A live test listing stays invisible | integration | any public read path returns it |
| Hold works on the matched side too (D25) | integration | the older property publishes while the newcomer is held |
| Purge clears every dependent row (D28) | integration | photos, proofs, listings, refs or flags survive their property |
| One failing property does not stop the sweep | integration | a RESTRICT row wedges the whole job |
| Every write route is duplicate-proof without a key (D36) | integration | any route creates a second row on a blind retry |
| Public JSON shape | golden | new fields are missing or renamed |
Risks and the known limit
| Risk | Mitigation |
|---|---|
A bad PUT wedges a landlord's sync with permanent ambiguity | The fingerprint is unique per landlord in the database (D33), so the ambiguity cannot be created |
| A fingerprint false hit overwrites a real property | NULL fingerprint when not confident (D18); per-source refs make step 2 rare; no fuzzy matching |
| A first sync duplicates an existing portfolio | Landed rows backfilled (D30); unit-less condos refuse with 409 unit_number_required (D29) |
| A fingerprint miss creates a duplicate | Per-source refs mean repeat syncs never reach the fingerprint; the admin flag catches cross-landlord cases |
| The purge wedges on one bad row and stops forever | Per-property transactions, failures logged and skipped (D28) |
| A test row reaches the public marketplace | Single choke point in publicScope; an integration test walks every public read path |
| The publication hold stalls a real landlord | Applies only when the other side has a verified proof, re-read at submit time (D25); admin can clear it |
| Two writers disagree about the address and fight nightly | Not solved in this slice. Merge on match (D24) stops phantom changes; a real disagreement needs field-ownership rules |
| A normalizer change silently re-buckets existing rows | Fingerprints are recomputed only on write; a normalizer change needs a deliberate backfill, not in this slice |
| POST changing from 201 to 200 breaks an early integrator | v1 has no external consumers yet; documented in rental-v1.yaml before any are onboarded |
Out of scope
Photo and media sync of any kind, proof upload over the API, outbound
webhooks, and the CLI. These are Slices 3 to 5. Landlord-visible adoption
history is also excluded — the adopt audit row (D35) is enough
to answer the question after the fact, and task 16 is already the only
frontend work in this slice.