Relay Parcel Matcher

Problem

A parcel relay uses spare capacity on published travel plans. Design RelayParcelMatcher to publish parcels and plans, rank compatible options, reserve capacity, and record each assignment transition from reservation through confirmation or cancellation. Calls are sequential and use one matcher instance.

Requirements

Injected compatibility. The non-null RouteCompatibilityPolicy is the only source of route compatibility. Its pure, deterministic score method returns -1 for an incompatible route or an integer from 0 to 1,000,000 for a compatible route, where a lower score is better.
Valid text. A parcel ID, travel plan ID, origin, or destination is valid when it has 1 to 64 characters, and every character is an ASCII letter, digit, hyphen, underscore, period, or colon.
Parcel publication. publishParcelRequest accepts a unique valid parcel ID, valid route points, and a weight from 1 to 1,000,000. It returns true and stores the request on success. Invalid or duplicate input returns false without changing state.
Plan publication. publishTravelPlan accepts a unique valid plan ID, valid route points, and a capacity from 1 to 1,000,000. It returns true and stores the plan on success. Invalid or duplicate input returns false without changing state. Parcel and plan IDs use separate namespaces.
Eligible matches. An open parcel can match a plan only when the policy score is non-negative and the plan's available capacity is at least the parcel weight.
Ranking. findMatches orders eligible plans by lower policy score, then lower capacity remaining after a reservation, then earlier successful plan publication. It returns at most limit plan IDs and does not change state.
Search failures. findMatches returns an empty list when the parcel is missing or not open, or when limit is outside 1 through 100.
Reservation. reserve does not require a prior search. It rechecks that both records exist, the parcel is open, the route is compatible, and enough capacity remains. On success it subtracts the parcel weight once, creates a reserved assignment, appends a RESERVED event, and returns a new match ID. Failure returns an empty string without changing state.
Assignment limit. A parcel has at most one reserved or confirmed assignment. Available capacity always equals declared capacity minus the weights of reserved and confirmed assignments, and never becomes negative.
Match IDs. Successful reservations receive match-1, match-2, and so on. Failed calls do not consume an ID.
Confirmation. confirmHandoff changes the parcel's current reserved assignment to confirmed, appends one CONFIRMED event, and returns true. The parcel becomes terminal and its capacity remains consumed. A missing parcel or any other state returns false without changing state.
Cancellation. cancelUnconfirmedMatch changes the parcel's current reserved assignment to cancelled, restores its weight exactly once, reopens the parcel, appends one CANCELLED event, and returns true. A missing parcel or any other state returns false without changing state.
Reassignment. A cancelled parcel may be reserved again. Earlier assignment events remain in its history.
History. Each successful reservation, confirmation, or cancellation appends one immutable AssignmentEvent. Event sequences are globally contiguous integers starting at 1; failed calls consume no sequence. getAssignmentHistory returns event snapshots for the requested parcel in sequence order, or an empty list when no events exist.
Capacity lookup. getAvailableCapacity returns a plan's remaining capacity, or -1 for an unknown plan.
Failure atomicity. Every rejected operation preserves records, publication order, assignments, capacity, match IDs, event sequences, and history.

API

Signature	Returns	Behavior
`RouteCompatibilityPolicy.score(parcelOrigin: string, parcelDestination: string, travelOrigin: string, travelDestination: string)`	`integer`	Returns `-1` for incompatibility or a score from `0` to `1,000,000`; it has no side effects.
`RelayParcelMatcher(routePolicy: RouteCompatibilityPolicy)`	Not applicable	Retains the non-null policy. A null policy raises the runtime's standard invalid-argument error.
`publishParcelRequest(parcelId: string, origin: string, destination: string, weight: integer)`	`boolean`	Publishes a valid unique parcel request.
`publishTravelPlan(travelPlanId: string, origin: string, destination: string, capacity: integer)`	`boolean`	Publishes a valid unique travel plan.
`findMatches(parcelId: string, limit: integer)`	`string[]`	Returns the ranked eligible plan IDs, subject to the search rules.
`reserve(parcelId: string, travelPlanId: string)`	`string`	Reserves compatible capacity and returns a generated match ID, or returns an empty string.
`confirmHandoff(parcelId: string)`	`boolean`	Confirms the parcel's current reserved assignment when present.
`cancelUnconfirmedMatch(parcelId: string)`	`boolean`	Cancels the parcel's current reserved assignment when present.
`getAvailableCapacity(travelPlanId: string)`	`integer`	Returns remaining capacity, or `-1` for an unknown plan.
`getAssignmentHistory(parcelId: string)`	`AssignmentEvent[]`	Returns immutable event snapshots in ascending sequence order.

AssignmentEvent has immutable fields sequence: integer, matchId: string, parcelId: string, travelPlanId: string, eventType: string, and weight: integer. eventType is RESERVED, CONFIRMED, or CANCELLED.

Examples

For one matcher, suppose the policy gives score 1 to both listed plans for parcel parcel-1.

Step	Operation	Result
1	`publishParcelRequest("parcel-1", "a", "b", 2)`	`true`
2	`publishTravelPlan("plan-a", "x", "y", 5)`	`true`
3	`publishTravelPlan("plan-b", "u", "v", 4)`	`true`
4	`findMatches("parcel-1", 5)`	`["plan-b", "plan-a"]` because their post-reservation capacities are `2` and `3`
5	`reserve("parcel-1", "plan-b")`	`"match-1"`
6	`getAvailableCapacity("plan-b")`	`2`
7	`confirmHandoff("parcel-1")`	`true`
8	`cancelUnconfirmedMatch("parcel-1")`	`false`

For a separate matcher, reserve a weight-2 parcel on a capacity-3 compatible plan. The reservation returns match-1; cancellation returns true and restores capacity to 3; repeated cancellation returns false; reserving the reopened parcel returns match-2. Its history contains RESERVED, CANCELLED, and RESERVED events with sequences 1, 2, and 3.

Constraints

At most 2,000 parcel requests and 2,000 travel plans are published successfully.
At most 20,000 public method calls are made on one matcher.
Weight, capacity, and compatible policy score are at most 1,000,000.
Capacity arithmetic fits a signed integer through 2,000,000,000.

Notes

Calls are sequential. Concurrency, route geography inside the matcher, dates, detours, live location, parcel splitting, record updates or deletion, plan cancellation, expiration, confirmed-assignment cancellation, journey completion, authentication, payment, messaging, persistence, external I/O, and policy failures or mutation are outside the contract.

Custom testcases supply compatibilityRules to the driver. Each rule names the four route strings and its score. The driver injects a policy that returns the declared score for an exact tuple and -1 for an unlisted tuple.