@jsm-mit/tigi-sharded-package 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+# @jsm-mit/tigi-sharded-package
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The one package of the Tigi network group: it takes the coordinator's id and hides the
+coordinator, the core and the workers — for a consumer the group is one canister. It also
+carries the rider's few driver-canister endpoints (U-14: `getRide`, `cancelRide`,
+`getLicence`), built from `protocol/tigi-driver.did`, so the consumer never sees a driver
+canister's id.
+
+Status: the rider's side (night 1, U-42); 0.2.0 (stage 2a, U-43) adds the rider's own
+rating and WHERE the chat with a driver is. Version 0.1.0 was the first to publish.
+
+## The rider
+
+```ts
+import { ProfilesActor, RidesActor, TestManagerActor, REQUEST_POLL_MS } from "@jsm-mit/tigi-sharded-package";
+
+const profiles = new ProfilesActor(coordinatorId, identity, { host });
+await profiles.setMyProfileAsyncUnsafe("Ala");             // C-2: once, before the first request
+
+const rides = new RidesActor(coordinatorId, identity, { host });
+const request = await rides.requestRideAsyncUnsafe({ pickup, destination });
+localStorage.setItem("tigi-request", request.token);       // rides.resumeRequest(token) after a reload
+
+const snapshot = await request.getAsyncUnsafe();            // every REQUEST_POLL_MS (1 s)
+// snapshot.phase: searching | waitingForDriver ("Zamawiam…", a second or two) | accepted | closed
+// snapshot.offers: a FIXED list (U-42) — by first arrival, new ones at the end, nothing
+//   re-sorted; an offer that left keeps its entry with `gone` (rejected | driverNotFree |
+//   taken | closed): draw a grey row of the same height there
+await request.rejectOfferAsyncUnsafe(offer.offerId);        // ✕ → gone "rejected"; the next nearest driver
+await request.refreshOfferAsyncUnsafe(offer.offerId);       // a stale (grey) offer asks again
+await request.chooseOfferAsyncUnsafe(offer.offerId);        // ordered (= the ride, accepted at once) | busy | offerExpired
+                                                            // | driverNotFree ("Kierowca jest już zajęty") | closed
+await request.giveUpAsyncUnsafe();
+// After "Kierowca anulował kurs" (ride status cancelledByDriver): "Szukaj ponownie" —
+const again = await request.searchAgainAsyncUnsafe();       // a new request, the same pickup and destination
+
+const ride = await request.getRideAsyncUnsafe();            // from the driver canister, every RIDE_POLL_MS (2 s)
+await request.cancelRideAsyncUnsafe();                      // before inProgress, once
+await request.getLicenceAsyncUnsafe();                      // from accepted to the end of the ride
+await request.rateDriverAsyncUnsafe(5);                     // after completed, once
+
+const page = await profiles.getMyRidesAsyncUnsafe();        // the history in the core, 20 a page
+const mine = await profiles.getMyRatingAsyncUnsafe();       // PF-4: { average: 4.87, count, sum } | undefined ("Brak ocen")
+await rides.getPastRideAsyncUnsafe(page.rides[0].rideRef);  // its details from the driver canister
+```
+
+What the package does for the network (zgloszenie-i-oferty.md):
+
+- the request goes to every worker whose area reaches 3 km around the pickup (ZO-1), found
+  with the coordinator's prefix map (kept 30 s; a worker's `NOT_MY_AREA` makes it ask again);
+- 15 s without an offer → 6 km, in the same and in new workers (ZO-8), inside `getAsyncUnsafe`;
+- one choice at a time over all the workers (ZO-14); after an acceptance,
+  `closeRequest otherOfferChosen` in the other workers (ZO-15);
+- a stopped canister (an upgrade, IC0508/IC0509) is waited out for about a minute.
+
+Errors: `CanisterError` (with `errorKey`; `refusalKeyOf(err)` gives the worker's refusal:
+`ALREADY_OPEN`, `NOT_MY_AREA`, `FULL`, `CLOSED`, `ORDERING`, `DRIVER_NOT_FREE`,
+`NOT_COMPLETED`, `EXPIRED`, `BLOCKED`), `CallRefusedAtInspectionStage`,
+`CriticalCanisterError`.
+
+## For the fronts: the chat (U-43)
+
+One chat room per DRIVER in `chat-sharded` (not per ride): its recipient is the owner of
+the driver canister, and every Tigi account may open a chat there (the chat asks the Tigi
+coordinator WHERE the accounts are and the core `isUser`). The core makes the rooms through
+the coordinator; this package only says WHERE — the fronts send and read messages with
+`@jsm-mit/chat-sharded-package` themselves (this package does not wrap the chat).
+
+```ts
+import { ChatPlacesActor, driverRoomId } from "@jsm-mit/tigi-sharded-package";
+import { ChatsActor, MessagesActor } from "@jsm-mit/chat-sharded-package";
+
+// The rider (PR-25): from `accepted` to the end of the ride.
+const place = await request.getChatPlaceAsyncUnsafe();      // { chatCoordinatorId, projectId, roomId } | undefined
+if (place) {
+    const chats = new ChatsActor(place.chatCoordinatorId, identity, { host });
+    const chat = await chats.openChatAsyncUnsafe({ projectId: place.projectId, roomId: place.roomId, customerName: profile.name });
+    // … MessagesActor(place.chatCoordinatorId, identity).postAsyncUnsafe / pollNewMessagesAsyncUnsafe
+}
+
+// The driver (FK-20): the room of their own canister; they are its recipient.
+const driverPlace = await new ChatPlacesActor(coordinatorId, identity, { host }).getDriverChatPlaceAsyncUnsafe(myDriverCanisterId);
+// list the chats of driverPlace.roomId (ChatsActor.getMyChatsAsyncUnsafe({ projectId, roomId }))
+// and show only the current rider's chat
+```
+
+- `undefined` = no chat in this environment yet (no chat config in the core) or a
+  simulated driver (no chat in MVP).
+- The room id is deterministic: `driverRoomId(canister)` = `drv-<canister id>` (the
+  core's `ChatRoomFunctions.driverRoomId`).
+- The rider needs a Tigi profile (`setMyProfileAsyncUnsafe`) — without one the chat
+  refuses to open it (`CanisterError`, `NotAuthorized`).
+- One chat per (room, rider, recipients): the rider has one chat with a driver over all
+  their rides. A demo pool canister taken over by another tester gets that tester as
+  the recipient; the chats with the previous tester stay with them.
+- The room may appear a few seconds after the driver's canister (the core's outbox);
+  `openChatAsyncUnsafe` answers `NotFound` until then — try again.
+
+The Test Manager (stage and the test modes): `TestManagerActor.hasSimulatedDriversAsyncUnsafe`,
+`spawnDriversAsyncUnsafe` (12 drivers), `setSpeedUpAsyncUnsafe(request, 10)` before choosing.
+Offers of the simulator have `simulated: true`.
+
+## Scripts
+
+```
+npm run build              # tsc (src → dist) and the type-check of the tests
+npm run test-unit          # no replica needed
+npm run test-drivers       # (a) 5 real driver canisters, driver-bots, route-stub
+npm run test-simulator     # (b) the simulator, 20 requests, 20 rides
+npm run test-split         # (c) an area split during traffic
+npm run test-smoke         # one whole ride with the simulator (run by publish-public)
+npm run publish-public     # human-run: publish from master (see below)
+npm run sync-declarations  # after a change of a .did (`… protocol` for the protocol and the simulator only)
+```
+
+The end-to-end suites run on the LOCAL replica only (`scripts/run-tests-local.sh`): a fresh
+group, local cycles, the driver and simulator wasms of `../../tigi-driver-rust` (built
+there, never changed). Logs and measurements go to `/tmp/claude-1000/tigi/`
+(`TEST_LOG_DIR`).
+
+## Publishing
+
+Human-run only: bump `version` in `package.json` by hand (do not commit it), then
+`npm run publish-public` on `master`. The script refuses unless this repo and
+`../../tigi-driver-rust` are both on a clean `master` equal to `origin/master`, the version is
+new on npm, the declarations match the current builds (core, worker, coordinator, protocol,
+simulator) and the smoke test passes on the LOCAL replica (`dfx start` first). It stamps
+`tigiSharded.commit` and `tigiDriverRust.commit` into `package.json`, publishes, then commits
+"Version bump to <version>" and pushes.