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

package/README.md

@@ -1,3 +1,89 @@
-# 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). Version 0.1.0 is 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
+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`.
+
+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.