@jsm-mit/tigi-sharded-package 0.3.0 → 0.5.0

package/README.md

@@ -3,12 +3,16 @@
 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
+`getLicence`, `getRideRoute`), 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; 0.3.0 (U-45) adds `DriverCanistersActor` — the
-demo lease and the one-time claim code. Version 0.1.0 was the first to publish.
+demo lease and the one-time claim code; 0.4.0 (route line, 2026-10-24) adds the driver's
+route on the map — the line of a tapped offer, the line of the ride — and the exact pin of
+an offer (`pinExact`); 0.5.0 (stage 7, ride history, 2026-10-24) adds the places of a past
+ride (Skąd, Dokąd) and the rating of a past ride from the history. Version 0.1.0 was the
+first to publish.
 
 ## The rider
 
@@ -27,6 +31,8 @@ const snapshot = await request.getAsyncUnsafe();            // every REQUEST_POL
 // 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
+// offer.pin: the driver's exact position (offer.pinExact) — the geohash7 centre from an old driver canister
+const line = await request.getOfferRouteAsyncUnsafe(offer.offerId);  // ZO-21, after a tap: { toPickup: Geo[]; ride: Geo[] } | undefined
 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
@@ -36,11 +42,17 @@ await request.giveUpAsyncUnsafe();
 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.getRideRouteAsyncUnsafe();                    // K-13: the ride's line while it is active (once; undefined after the end)
 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
+// 0.5.0 — a line: pickup?, destination? (KU-4; none before stage 7), ratable (KU-5), myRating?
+const past = await profiles.getMyRideAsyncUnsafe(page.rides[0].rideRef);  // one line (a reload); undefined until the core has it
+if (past?.ratable) await profiles.ratePastRideAsyncUnsafe(past.rideRef, 5);
+//   → "ok" | "alreadyRated" (also after rateDriverAsyncUnsafe) | "notRatable" (not completed,
+//     the 24 h are over, not in the core yet) | "notAuthorized" (another rider's ride)
 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
 ```
@@ -148,6 +160,8 @@ npm run test-drivers       # (a) 5 real driver canisters, driver-bots, route-stu
 npm run test-simulator     # (b) the simulator, 20 requests, 20 rides
 npm run test-split         # (c) an area split during traffic
 npm run test-claim         # (d) the demo lease and the claim code (U-45)
+npm run test-route-line    # (e) the route line of an offer and of a ride
+npm run test-ride-history  # (f) the history's places and the rating of a past ride (0.5.0)
 npm run test-smoke         # one whole ride with the simulator (run by publish-public)
 npm run load-local         # the load test: 200 simulated drivers, 100 riders (docs/load-test-2026-10-24.md)
 npm run publish-public     # human-run: publish from master (see below)

package/declarations/coordinator/coordinator.did

@@ -48,8 +48,16 @@ type Config = record {
   wasm : opt WasmInfo;
   // Somebody who asked for the superadmin role (LIVE; one request a day for the group).
   roleRequest : opt RoleRequest;
+  // KO-19 (U-46): the cycles per canister of the group below which the fee multiplier
+  // goes up and above which it goes down. None = the defaults.
+  feeThresholds : opt FeeThresholds;
+  // KO-20: every fee cycle the core forwarded, in total.
+  feesReceived : opt nat;
   // The UTC day of the last request: a second request the same day is refused in inspect.
   lastRequestDay : nat64;
+  // KO-19: the multiplier of the drivers' daily fee, recomputed at most once a UTC day.
+  // None = never computed (the start value counts).
+  feeMultiplier : opt FeeMultiplierState;
   // What a new worker starts with, and what a worker or the core gets when it reports a
   // low balance. A worker asks below half of it.
   cyclesPerWorker : nat;
@@ -135,6 +143,26 @@ type Event = record {
   kind : text;
   "text" : text;
 };
+type FeeMultiplier = record { day : nat64; permille : nat32 };
+// KO-19: the core asks for the multiplier of its fee day.
+type FeeMultiplierArgs = record { day : nat64 };
+// KO-19: the multiplier of one UTC day and what it was computed from.
+type FeeMultiplierState = record {
+  day : nat64;
+  // In thousandths: 1200 = 1.2.
+  permille : nat32;
+  // The canisters whose balance was not read at that reading ("<id>: <error>"), left out
+  // of the sum and of N. Not empty = an alarm on the front.
+  unread : opt vec text;
+  // The balances of the coordinator, the core and the workers read that day.
+  groupSum : opt nat;
+  computedAtNs : opt nat64;
+  // N: the canisters read (workers + core + coordinator).
+  canisters : opt nat32;
+};
+// KO-19: per canister of the group (the coordinator, the core, every worker). Defaults:
+// `DEFAULT_FEE_MIN_PER_CANISTER`, `DEFAULT_FEE_MAX_PER_CANISTER`.
+type FeeThresholds = record { minPerCanister : nat; maxPerCanister : nat };
 // The arguments of the method are the core's, Candid-encoded (`to_candid` in Motoko) —
 // the coordinator does not read them and keeps no copy of the chat group's types.
 type ForwardChatAdminArgs = record {
@@ -545,6 +573,12 @@ service : (InitArgs) -> {
   forwardChatAdmin : (ForwardChatAdminArgs) -> (Result_7);
   // What the core says of itself right now — one composite query for the front.
   getCoreStatus : () -> (Result_8) composite_query;
+  // KO-19 (U-46): the multiplier of the drivers' daily fee for the core's fee day —
+  // recomputed lazily, at most once a UTC day, when the core asks at the day's first
+  // settlement (no timer). The sum of the balances of the coordinator, the core and every
+  // worker against N × the thresholds (N = the canisters read). A reading already running
+  // answers the multiplier as it is. Only the core of this group (a trap otherwise).
+  getFeeMultiplier : (FeeMultiplierArgs) -> (FeeMultiplier);
   // The core of the group.
   getHomeCanister : () -> (opt principal) query;
   // The whole prefix map: which worker serves which area.
@@ -624,6 +658,8 @@ service : (InitArgs) -> {
   // `maxWorkers`, the query thresholds. Only the fields given are changed.
   setConfig : (SetConfigArgs) -> (Result_16);
   setCoreLoggingEnabled : (CoreLoggingArgs) -> (Result_11);
+  // KO-19: the superadmin sets the thresholds of the fee multiplier (cycles per canister).
+  setFeeThresholds : (FeeThresholds) -> (Result_16);
   // The config of the workers of the group: the load thresholds, logging. Only the fields
   // given are changed. The result is stored, given to every worker that has its code, and
   // to every worker created later.
@@ -637,6 +673,9 @@ service : (InitArgs) -> {
   // A worker of the group sends its cycles here before it is deleted (`giveBackCycles`).
   // The workers only: somebody else's cycles are refused (they go back to the sender).
   takeCycles : () -> (nat);
+  // KO-20 (U-46): the drivers' fees the core took, forwarded here — every attached cycle is
+  // accepted and counted. No per-driver data: the bills are the core's. Only the core.
+  takeFeeCycles : () -> (nat);
   // Cycles for the core, by hand: `cyclesPerWorker`, like a worker's top-up.
   topUpCore : () -> (Result_20);
   // Cycles for a worker, by hand.

package/declarations/coordinator/coordinator.did.d.ts

@@ -88,10 +88,24 @@ export interface Config {
    * Somebody who asked for the superadmin role (LIVE; one request a day for the group).
    */
   'roleRequest' : [] | [RoleRequest],
+  /**
+   * KO-19 (U-46): the cycles per canister of the group below which the fee multiplier
+   * goes up and above which it goes down. None = the defaults.
+   */
+  'feeThresholds' : [] | [FeeThresholds],
+  /**
+   * KO-20: every fee cycle the core forwarded, in total.
+   */
+  'feesReceived' : [] | [bigint],
   /**
    * The UTC day of the last request: a second request the same day is refused in inspect.
    */
   'lastRequestDay' : bigint,
+  /**
+   * KO-19: the multiplier of the drivers' daily fee, recomputed at most once a UTC day.
+   * None = never computed (the start value counts).
+   */
+  'feeMultiplier' : [] | [FeeMultiplierState],
   /**
    * What a new worker starts with, and what a worker or the core gets when it reports a
    * low balance. A worker asks below half of it.
@@ -227,6 +241,43 @@ export interface Event {
   'kind' : string,
   'text' : string,
 }
+export interface FeeMultiplier { 'day' : bigint, 'permille' : number }
+/**
+ * KO-19: the core asks for the multiplier of its fee day.
+ */
+export interface FeeMultiplierArgs { 'day' : bigint }
+/**
+ * KO-19: the multiplier of one UTC day and what it was computed from.
+ */
+export interface FeeMultiplierState {
+  'day' : bigint,
+  /**
+   * In thousandths: 1200 = 1.2.
+   */
+  'permille' : number,
+  /**
+   * The canisters whose balance was not read at that reading ("<id>: <error>"), left out
+   * of the sum and of N. Not empty = an alarm on the front.
+   */
+  'unread' : [] | [Array<string>],
+  /**
+   * The balances of the coordinator, the core and the workers read that day.
+   */
+  'groupSum' : [] | [bigint],
+  'computedAtNs' : [] | [bigint],
+  /**
+   * N: the canisters read (workers + core + coordinator).
+   */
+  'canisters' : [] | [number],
+}
+/**
+ * KO-19: per canister of the group (the coordinator, the core, every worker). Defaults:
+ * `DEFAULT_FEE_MIN_PER_CANISTER`, `DEFAULT_FEE_MAX_PER_CANISTER`.
+ */
+export interface FeeThresholds {
+  'minPerCanister' : bigint,
+  'maxPerCanister' : bigint,
+}
 /**
  * The arguments of the method are the core's, Candid-encoded (`to_candid` in Motoko) —
  * the coordinator does not read them and keeps no copy of the chat group's types.
@@ -824,6 +875,14 @@ export interface _SERVICE {
    * What the core says of itself right now — one composite query for the front.
    */
   'getCoreStatus' : ActorMethod<[], Result_8>,
+  /**
+   * KO-19 (U-46): the multiplier of the drivers' daily fee for the core's fee day —
+   * recomputed lazily, at most once a UTC day, when the core asks at the day's first
+   * settlement (no timer). The sum of the balances of the coordinator, the core and every
+   * worker against N × the thresholds (N = the canisters read). A reading already running
+   * answers the multiplier as it is. Only the core of this group (a trap otherwise).
+   */
+  'getFeeMultiplier' : ActorMethod<[FeeMultiplierArgs], FeeMultiplier>,
   /**
    * The core of the group.
    */
@@ -955,6 +1014,10 @@ export interface _SERVICE {
    */
   'setConfig' : ActorMethod<[SetConfigArgs], Result_16>,
   'setCoreLoggingEnabled' : ActorMethod<[CoreLoggingArgs], Result_11>,
+  /**
+   * KO-19: the superadmin sets the thresholds of the fee multiplier (cycles per canister).
+   */
+  'setFeeThresholds' : ActorMethod<[FeeThresholds], Result_16>,
   /**
    * The config of the workers of the group: the load thresholds, logging. Only the fields
    * given are changed. The result is stored, given to every worker that has its code, and
@@ -976,6 +1039,11 @@ export interface _SERVICE {
    * The workers only: somebody else's cycles are refused (they go back to the sender).
    */
   'takeCycles' : ActorMethod<[], bigint>,
+  /**
+   * KO-20 (U-46): the drivers' fees the core took, forwarded here — every attached cycle is
+   * accepted and counted. No per-driver data: the bills are the core's. Only the core.
+   */
+  'takeFeeCycles' : ActorMethod<[], bigint>,
   /**
    * Cycles for the core, by hand: `cyclesPerWorker`, like a worker's top-up.
    */

package/declarations/coordinator/coordinator.did.js

@@ -116,6 +116,11 @@ export const idlFactory = ({ IDL }) => {
     'admins' : IDL.Opt(IDL.Vec(IDL.Principal)),
   });
   const Result_8 = IDL.Variant({ 'Ok' : CoreLive, 'Err' : CoordinatorError });
+  const FeeMultiplierArgs = IDL.Record({ 'day' : IDL.Nat64 });
+  const FeeMultiplier = IDL.Record({
+    'day' : IDL.Nat64,
+    'permille' : IDL.Nat32,
+  });
   const Event = IDL.Record({
     'id' : IDL.Nat64,
     'atNs' : IDL.Nat64,
@@ -191,6 +196,18 @@ export const idlFactory = ({ IDL }) => {
     'load' : IDL.Opt(LoadThresholds),
     'loggingEnabled' : IDL.Opt(IDL.Bool),
   });
+  const FeeThresholds = IDL.Record({
+    'minPerCanister' : IDL.Nat,
+    'maxPerCanister' : IDL.Nat,
+  });
+  const FeeMultiplierState = IDL.Record({
+    'day' : IDL.Nat64,
+    'permille' : IDL.Nat32,
+    'unread' : IDL.Opt(IDL.Vec(IDL.Text)),
+    'groupSum' : IDL.Opt(IDL.Nat),
+    'computedAtNs' : IDL.Opt(IDL.Nat64),
+    'canisters' : IDL.Opt(IDL.Nat32),
+  });
   const Config = IDL.Record({
     'maxWorkers' : IDL.Opt(IDL.Nat64),
     'coreWasm' : IDL.Opt(WasmInfo),
@@ -203,7 +220,10 @@ export const idlFactory = ({ IDL }) => {
     'workerConfig' : IDL.Opt(WorkerConfigArgs),
     'wasm' : IDL.Opt(WasmInfo),
     'roleRequest' : IDL.Opt(RoleRequest),
+    'feeThresholds' : IDL.Opt(FeeThresholds),
+    'feesReceived' : IDL.Opt(IDL.Nat),
     'lastRequestDay' : IDL.Nat64,
+    'feeMultiplier' : IDL.Opt(FeeMultiplierState),
     'cyclesPerWorker' : IDL.Nat,
     'spread' : IDL.Bool,
     'nextEventId' : IDL.Nat64,
@@ -367,6 +387,7 @@ export const idlFactory = ({ IDL }) => {
     'drainWorker' : IDL.Func([DrainWorkerArgs], [Result_6], []),
     'forwardChatAdmin' : IDL.Func([ForwardChatAdminArgs], [Result_7], []),
     'getCoreStatus' : IDL.Func([], [Result_8], ['composite_query']),
+    'getFeeMultiplier' : IDL.Func([FeeMultiplierArgs], [FeeMultiplier], []),
     'getHomeCanister' : IDL.Func([], [IDL.Opt(IDL.Principal)], ['query']),
     'getPrefixMap' : IDL.Func([], [IDL.Vec(PrefixEntry)], ['query']),
     'getRoles' : IDL.Func([], [Roles], ['query']),
@@ -400,10 +421,12 @@ export const idlFactory = ({ IDL }) => {
     'resetGroup' : IDL.Func([], [Result_15], []),
     'setConfig' : IDL.Func([SetConfigArgs], [Result_16], []),
     'setCoreLoggingEnabled' : IDL.Func([CoreLoggingArgs], [Result_11], []),
+    'setFeeThresholds' : IDL.Func([FeeThresholds], [Result_16], []),
     'setWorkerConfig' : IDL.Func([WorkerConfigArgs], [Result_17], []),
     'setWorkerOpen' : IDL.Func([SetWorkerOpenArgs], [Result_18], []),
     'splitWorker' : IDL.Func([CanisterArgs], [Result_19], []),
     'takeCycles' : IDL.Func([], [IDL.Nat], []),
+    'takeFeeCycles' : IDL.Func([], [IDL.Nat], []),
     'topUpCore' : IDL.Func([], [Result_20], []),
     'topUpWorker' : IDL.Func([CanisterArgs], [Result_20], []),
     'upgradeCore' : IDL.Func([], [Result_3], []),