Slice 3 — guest timeline and attributed decisions

[robertblust]

Source business objects (reservations first) become associations on resolved guests, answering "what does this guest currently have" rather than only "what did we ever observe about them". Every decision now names the actor that made it: the system, a named human steward, or a named agent.

Spec, plan, research and tasks are in specs/003-timeline-journey/ (committed separately in c79cd84 so the requirements are reviewable apart from the code).

The central decision

The object version is the unit of supersession. Each version's observations form a complete roster, and the newest roster alone decides who is on an object — persons are never matched from one version to the next.

This is the crux, and it departs from the roadmap sketch. Sources carrying entity-less persons (Apaleo reservations) give no id to follow across edits, so any slot-tracking scheme has to guess, and reports a reassignment every time a booking's guest list shrinks. The roster model also makes removal detectable: dropping one of two additional guests no longer reports the other as their replacement.

What's new

• GET /guests/{id}/timeline — current associations, includePast for ended ones, keyset-cursor paged, ordered by business start
• GET /source-objects/{system}/{type}/{id} — an object's current roster and full observation history, which spans guests after a reassignment
• POST /records accepts an optional sourceObject block

Associations are derived on read and never persisted, so recomputability (FR-010) is structural rather than maintained across four mutation points, and a roster read mid-delivery self-heals with no convergence logic (FR-010a).

Three things that need an explicit nod

1. FR-007 changed during implementation. Writing the deriver tests showed the spec's successor rule — "name the current holder when the roster has exactly one guest in that role" — would name Zoe as Yara's successor in [Yara, Zoe] → [Zoe], the exact fabricated transfer this design exists to prevent. It is now a genuine one-to-one handover. The spec commit and the implementation commit disagree on this; the second is right, and spec.md was updated in the same commit.

2. V3 is not purely additive. It drops negative_match_rule's pair unique constraint for a partial index over active rules, because rules are now lifted rather than deleted (overriding a steward's split is itself a decision that needs an actor, and a deleted row has nowhere to keep one). Safe only because nothing is released — please confirm you're happy with that rather than letting it slip past.

3. Two earlier slices' endpoints changed./match-reviews and /negative-rules moved off raw limit/offset onto the same opaque keyset cursor, and their contracts changed with them. Scope beyond this slice's stories, taken deliberately (research R9) so the API has one paging idiom while that is still free to change. It also fixes a real wart: under offsets, reviews decided mid-traversal shifted the remaining rows and clients silently skipped entries. This narrows SC-008 to resolution behaviour, which the spec now says.

Schema

V3__timeline_and_actors.sql adds record_object — an immutable companion of source_record, following the record_identifier / record_block_key precedent so source_record's immutability trigger stays untouched — plus actor columns on merge_event, negative_match_rule, and api_key.

Actor type is bound to the credential (the trust boundary); X-Actor-Id may name the individual behind a shared credential but can never widen the type. ResolutionEngine takes no actor parameter at all, so automatic resolution has no code path to being attributed to a person.

Verification

• 198 tests, ArchUnit, PMD, Spotless, and the two-way OpenAPI gate over all three feature contracts
• ER diagram regenerated; er-drift job passes locally
• Quickstart walked end to end against a running instance, including LocalDevSeeder against V3
• SC-006 measured at ~2,500 observations (the sizing research R1 argues from): first page well under 1s

A code review pass caught one real bug worth flagging: the timeline's ordering key was not total, so a page boundary between two entries of the same object (a booker who is also the primary guest) silently dropped one. Fixed with a single ordering key shared by the sort, the cursor, and the seek.

Deliberately not in this slice

The FR-011 agent carve-out — an agent may not lift a human's split — is now enabled (both actors sit on one rule row) but not enforced; it belongs with scoped credentials in slice 5. Recorded in docs/roadmap-notes.md under R5-1.

🤖 Generated with Claude Code