@jsm-mit/tigi-sharded-package 0.2.0 → 0.4.0

package/README.md

@@ -3,11 +3,14 @@
 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. Version 0.1.0 was the first to publish.
+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; 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`). Version 0.1.0 was the first to publish.
 
 ## The rider
 
@@ -26,6 +29,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
@@ -35,6 +40,7 @@ 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
@@ -96,6 +102,44 @@ const driverPlace = await new ChatPlacesActor(coordinatorId, identity, { host })
 - The room may appear a few seconds after the driver's canister (the core's outbox);
   `openChatAsyncUnsafe` answers `NotFound` until then — try again.
 
+## For the fronts: the driver's own canister (U-45)
+
+Internet Identity gives one person a different principal on every origin. The demo lease is
+taken on the rider's site; the driver signs in on the canister's own front
+(`https://<canister>.icp0.io`) with another principal. A fresh lease answers a one-time
+claim code (15 min, single use; the core keeps only its sha256) that hands the canister to
+whoever claims it there (`fabryka.md` F-20).
+
+```ts
+import { DriverCanistersActor, claimLinkOf, claimCodeOfHash } from "@jsm-mit/tigi-sharded-package";
+
+// The rider's site (the lease holder).
+const canisters = new DriverCanistersActor(coordinatorId, identity, { host });
+const lease = await canisters.leaseDemoAsyncUnsafe();       // { kind: "leased", canister, claim? } | { kind: "busy", untilMs }
+if (lease.kind === "leased" && lease.claim) {
+    link = claimLinkOf(lease.canister.canisterId, lease.claim.code);   // "Otwórz swój kanister"
+}
+const fresh = await canisters.newClaimCodeAsyncUnsafe();    // "Nowy link": the old code stops working
+await canisters.extendDemoAsyncUnsafe();                    // F-8: 15 min more
+await canisters.getMineAsyncUnsafe();                       // the held demo canister (or the own one) | undefined
+
+// The driver's front, signed in as a non-owner, with #claim=<code> in the address.
+const code = claimCodeOfHash(window.location.hash);
+if (code) {
+    await new DriverCanistersActor(coordinatorId, identity, { host }).claimAsyncUnsafe(canisterId, code);
+    // clear the fragment, reload: the driver is the owner now
+}
+```
+
+- A refused claim is always `CanisterError` `NotAuthorized` — wrong, expired, used or not
+  this canister's code alike.
+- The lease stays with its holder: `getMineAsyncUnsafe`, `extendDemoAsyncUnsafe` and
+  `newClaimCodeAsyncUnsafe` keep working from the rider's site; `ownerPrincipal` names
+  the driver after the claim. The chat room of the canister gets the driver as its
+  recipient.
+- The same holder leasing again (no reinstall) gets no code: `newClaimCodeAsyncUnsafe`.
+- These views carry the driver canister's id: it is the driver's own address.
+
 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`.
@@ -108,7 +152,9 @@ 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-claim         # (d) the demo lease and the claim code (U-45)
 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)
 npm run sync-declarations  # after a change of a .did (`… protocol` for the protocol and the simulator only)
 ```
@@ -116,7 +162,9 @@ npm run sync-declarations  # after a change of a .did (`… protocol` for the pr
 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`).
+(`TEST_LOG_DIR`). The load test builds its group with its own coordinator
+(`tigi-sharded-coordinator-load`), so the shared local group stays; its settings are
+environment variables (`scripts/load-local.ts`, `scripts/run-load-local.sh`).
 
 ## Publishing
 

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], []),