@thegeem/protocol 0.1.37 → 0.1.40

package/copy-rules.json

@@ -0,0 +1,120 @@
+{
+  "$meta": {
+    "note": "THE COPY RULES, AS DATA. Banned words and digit ranges that every player-facing string in Geem must obey — on every client, in every language. Read this file; never re-type a word list.",
+    "why": "«قعدة» reached the store as the Arabic NAME of the only item sellable for real money, past six gates, because all six inspected ART and no art check can see a name. The relay then wrote a TS scanner and offered to publish it — which would have served the relay and the site and left iOS (Swift), Android and TV (Kotlin) reimplementing. Four copies with a shared name on two of them is WORSE than four copies, because it looks unified.",
+    "rule": "When sharing across languages, ask what must not diverge. If it is a VALUE, ship the value. Shipping the implementation only works where the runtime is shared, and it silently excludes whoever is not on it — the failure mode where the excluded party does not notice they were excluded.",
+    "authority": "geem-coordination/DECISIONS.md — D-039 (banned words), D-043 (Western digits), D-073 (normalise at the WRITE gate, never at render)",
+    "scanners": "One per language, each small. The relay's is relay/src/copyRules.ts. ⚠️ A scanner must assert it MATCHED something: a scan whose success condition is an empty result set gets more reliable the more broken your tooling is — broken glob, moved path, changed extension, zero literals, passes forever, invisibly.",
+    "reportNeverRewrite": "These rules REPORT. They must not silently rewrite a string: a second normaliser makes two clients disagree about what a thing is CALLED, which is worse than the original problem (D-073). The one gate that transforms is sanitizeName, and it guards text a PLAYER typed — not text we wrote.",
+    "updated": "2026-08-16",
+    "honestLimit": "⚠️ THIS LIST IS PERMANENTLY ADVISORY. Arabic is inflected and an enumeration cannot be complete, so passing these checks is NOT evidence that copy is clean — it only means the forms someone has thought of are absent. THE REAL CONTROL IS A KUWAITI READING PLAYER-FACING ARABIC BEFORE IT SHIPS. Mistaking the list for coverage is exactly what let «قعدتك» through. Add forms when one is found; never treat the file as the reason you did not look.",
+    "factsFile": "protocol/copy-facts.json — CFO-owned, and it does not exist yet (gs#110). This file owns the MECHANICS and carries no numbers; facts live in a file that owns them, the same split as ECONOMY.md + earn-table.json. A scanner must treat its absence as «no facts published», never as «no facts apply»."
+  },
+  "bannedWords": [
+    {
+      "forms": [
+        "قعدة",
+        "القعدة",
+        "قعدتك",
+        "قعدتنا",
+        "قعدته",
+        "قعدتها",
+        "قعدتهم",
+        "قعدتي",
+        "قعدات",
+        "القعدات",
+        "قعدتكم",
+        "قعدتهن",
+        "قعدتين",
+        "القعدتين"
+      ],
+      "ruling": "D-039",
+      "why": "In Kuwait the word mostly reads as a sitting for alcohol and music — disqualifying for a family game. The ban is «قعدة» and its forms, and nothing else. Where a container noun is unavoidable, use «غرفة»; everywhere the player acts, use a VERB and no container noun at all.",
+      "instead": "«غرفة» is the single permitted noun, and only where forced — the code and hard failures. Buttons and flow text carry no container noun at all.",
+      "formsNote": "The ة→ت POSSESSIVE family is the gap that let «قعدتك» ship in a released App Store build while three desks each trusted a two-item list nobody had measured. Enumerated, never stem-matched: a «قعد» stem flags «المقعد» (a seat) and «يقعدون» (they sit), both present in our own repos today — that is the noisy-check failure pre-loaded into the guard, and it would have taught every desk to ignore the copy scan within a week. ⚠️ «قعدتكم» was NAMED by the iOS desk on 2026-08-16 as missing and was still missing four days later: the enumeration was extended once, by hand, from one desk's examples — and a hand-extended list is complete exactly up to the examples someone happened to give. The plural-you and dual forms were added 2026-08-20 for the same reason, before anyone reported them.",
+      "correction": "⚠️ THIS `why` USED TO CLAIM A BAN THIS FILE NEVER CARRIED, and the sentence is quoted here rather than left in place: it said the ruling «rejects the whole gathering-word category», naming ديوانية as men's and يمعة as women's. The DATA never carried it — one entry, fourteen forms, every one a form of «قعدة». Owner, verbatim 2026-08-25: «I didn't banned مجالس i only banned قعدة». The gendered-words note was always the reason no other gathering word was picked AS THE REPLACEMENT — none is gender-neutral, so none works as a container noun — and «rejected as a replacement» is not «banned from all copy». D-077 carries the owner's companion rulings from the same week: «الديوانية» STAYS (it names the place drawn in the art) and «مجلس» is RENAMED. A category ban cannot survive its own author keeping one member of the category and merely re-labelling another. Corrected here 2026-08-26; the ledger row is D-093. ⚠️ IT IS A SEPARATE FIELD FROM `why` ON PURPOSE — `why` is what findings PRINT and what desks quote, so it must be the rule as it stands and nothing else. History in that string is how a retracted claim keeps circulating.",
+      "whyThisMattersBeyondOneWord": "⚠️ PROSE INSIDE A RULES FILE IS THE MOST DANGEROUS PROSE IN THE PROJECT — it is the only prose that inherits a checker's credibility. The file was correct exactly where it is enforceable and wrong exactly where it is narration, which is the worst split available. It produced a real wrong ruling: the CFO ruled «مجالس» banned in the 1.6.2 App Store listing, reading D-039's row CORRECTLY, and the owner overturned them personally. They did not misread — they read it right and it was wrong. The shape: a rules file has a reader and cannot overreach, a form is banned or it is not. A ledger row has no reader and can say anything. When they disagree, the row is what one desk quotes at another. IF `why` AND `forms` EVER DISAGREE AGAIN, FORMS WIN — they are what runs."
+    }
+  ],
+  "digits": {
+    "ruling": "D-043",
+    "why": "A digit is a glyph of a number, not identity. «سالم ١٧» and «سالم 17» are the same name for the same person, so normalising changes how a name is DRAWN, never who it refers to. Letters are never touched.",
+    "bannedRanges": [
+      {
+        "name": "Arabic-Indic",
+        "from": "٠",
+        "to": "٩"
+      },
+      {
+        "name": "Extended Arabic-Indic (Persian)",
+        "from": "۰",
+        "to": "۹"
+      }
+    ],
+    "use": "Western 0-9, every surface, every language."
+  },
+  "concepts": [
+    {
+      "id": "room",
+      "ruling": "D-039",
+      "requiredTerm": "غرفة",
+      "bannedForms": [
+        "قعدة",
+        "القعدة",
+        "قعدتك",
+        "قعدتنا",
+        "قعدته",
+        "قعدتها",
+        "قعدتهم",
+        "قعدتي",
+        "قعدات",
+        "القعدات",
+        "قعدتكم",
+        "قعدتهن",
+        "قعدتين",
+        "القعدتين"
+      ],
+      "scope": "only where a container noun is unavoidable — the code and hard failures. Buttons and flow text carry no container noun at all.",
+      "why": "A ban can only say NO. This says what to write instead, as DATA rather than prose, so a Swift or Kotlin scanner can act on it — `bannedWords[].instead` was already correct and already travelled with findings in the TS scanner, but it is a sentence, and a sentence is not a field.",
+      "whatItStillCannotDo": "⚠️ A required term only helps for a concept somebody has NAMED. It cannot notice that a new concept needs one. `$meta.honestLimit` still governs: this file is permanently advisory about words nobody has thought of.",
+      "⚠️ WHY «ديوانية» AND «يمعة» ARE NOT IN bannedForms": "The CFO's spec for this field (gs#110) listed «الليوان», «ليوان», «ديوانية» and «يمعة» as banned forms. **Adding them would have re-committed the exact error the owner corrected the day before.** Owner, verbatim 2026-08-25: «I didn't banned مجالس i only banned قعدة», and D-077 keeps «الديوانية» by name because it names the place drawn in the art. The CFO wrote their spec before that correction reached them — see `bannedWords[0].correction`. **This is the mechanism they asked for, doing the job they wanted, without the ban they did not have the authority to add.** «الليوان» is not banned either: it is wrong because it is not «غرفة», which is precisely what requiredTerm is for. A required term does the work a wider ban list was reaching for, and does it without banning words the owner permits."
+    }
+  ],
+  "noAbsolutePrices": {
+    "ruling": "CFO 2026-08-25 (gs#110)",
+    "why": "Apple renders the real localized price. A number written into copy is wrong in most territories and drifts from ASC the moment either changes. Measured from ASC: yearly Pro is $99.99 in the USA and 149.99 in Australia — one sentence naming an amount is wrong for most of the region the day it is written.",
+    "whyItIsAPROHIBITIONandNotAFACT": "⚠️ THE SHAPE IS THE POINT. iOS said «if the listing says $9.99 a month, I cannot evaluate that — only you know what is really sold.» Handing them the number would have been the obvious answer and the wrong one: a money fact copied into a second place drifts. A prohibition dissolves the problem instead — **any desk can check it with no CFO knowledge at all**, because it needs to know nothing except that a currency sits next to a numeral.",
+    "appliesTo": [
+      "App Store description",
+      "release notes",
+      "screenshots",
+      "in-app marketing copy"
+    ],
+    "currencyMarks": [
+      "$",
+      "€",
+      "£",
+      "KWD",
+      "USD",
+      "SAR",
+      "AED",
+      "QAR",
+      "BHD",
+      "OMR",
+      "EGP",
+      "د.ك",
+      "ر.س",
+      "د.إ",
+      "ر.ق",
+      "د.ب",
+      "ر.ع",
+      "ج.م",
+      "دينار",
+      "ريال",
+      "درهم",
+      "دولار"
+    ],
+    "instead": "name what it GRANTS, never what it costs. The store sheet carries the price, correctly, in the reader’s own currency.",
+    "notPlayerCoinAmounts": "⚠️ «600 دانات» IS NOT A PRICE UNDER THIS RULE and must never be flagged as one. دانات are an in-game currency this desk mints and can prove; the rule is about REAL money in a territory Apple prices. Flagging coin amounts would make the check red on the entire store and it would be switched off within a day."
+  }
+}

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CHARACTER_IDS: () => CHARACTER_IDS,
+  COMEBACK_BONUS_MIN_PV: () => COMEBACK_BONUS_MIN_PV,
   ClientMsg: () => ClientMsg,
   EMOTE_IDS: () => EMOTE_IDS,
   GAMES: () => GAMES,
@@ -30,11 +31,17 @@ __export(index_exports, {
   MODES: () => MODES,
   MODE_IDS: () => MODE_IDS,
   PROTOCOL_VERSION: () => PROTOCOL_VERSION,
+  REJECT_REASONS: () => REJECT_REASONS,
   ROOM_ALPHABET: () => ROOM_ALPHABET,
+  SUBMISSION_KINDS: () => SUBMISSION_KINDS,
+  SUBMISSION_STATUSES: () => SUBMISSION_STATUSES,
+  effectsForPv: () => effectsForPv,
   gameIdForPv: () => gameIdForPv,
   gamesForPv: () => gamesForPv,
+  hostActivityForPv: () => hostActivityForPv,
   modesForGame: () => modesForGame,
-  normalizeWesternDigits: () => normalizeWesternDigits
+  normalizeWesternDigits: () => normalizeWesternDigits,
+  sanitizeName: () => sanitizeName
 });
 module.exports = __toCommonJS(index_exports);
 var import_zod = require("zod");
@@ -47,9 +54,9 @@ var LIMITS = {
    *  Clients batch pen points to stay under this — ~150ms batching lands at ~7/sec. */
   STROKE_BATCH_PER_SEC: 20
 };
-var PROTOCOL_VERSION = 4;
+var PROTOCOL_VERSION = 7;
 var MIN_SUPPORTED_PV = 1;
-var GAME_IDS = ["seedha", "snag", "trivia", "dama", "ersimha"];
+var GAME_IDS = ["seedha", "snag", "trivia", "dama", "ersimha", "sebaq"];
 var GAMES = [
   { id: "seedha", label: "Seedha", minPv: 2 },
   { id: "snag", label: "Snag", minPv: 2 },
@@ -57,8 +64,30 @@ var GAMES = [
   // engine #2 (D-027) — offered only to pv≥3 clients
   { id: "ersimha", label: "Ersimha", minPv: 4 },
   // engine #3 (D-030) draw-and-guess — offered only to pv≥4 clients
+  // ⚠️ A NEW GAME, NOT A MODE OF SNAG, AND THE NAME COLLISION IS WHY IT HAD TO BE. `buzzerMode: 'race'`
+  // ALREADY MEANS ديوانية's buzz-race — everyone racing to buzz for ONE shared question. Sebaq is the
+  // opposite: no shared question, no buzzer, no turns. Every player runs the same set privately, at
+  // their own speed. Putting a mode called `race` beside a buzzerMode called `race`, meaning opposite
+  // things, one string apart on the wire, is the worst naming available here.
+  //
+  // It is also the wrong SHAPE for a mode: every MODES row is a way of playing seedha's turn loop —
+  // one question, one board, a shared clock. Sebaq uses none of it. A mode that shares no mechanic
+  // with its game is a game.
+  //
+  // ✅ NAME RULED BY THE OWNER, 2026-08-25: «سباق sebaq». Renamed from the provisional `sabag` before
+  // any client had shipped the string — which was the entire reason for saying it was provisional.
+  //
+  // ⚠️ `q` IS ق, AND IT IS NOT AN EXCEPTION TO THE BRAND RULE — I filed it as one and the owner
+  // corrected me. `CLAUDE.md`'s «Najdi ق = g» is about how ق SOUNDS in قييم; `q` is what the LETTER
+  // is. Two different questions, and `sebaq` answers the second. **Do not "fix" this to `sebag`.**
+  { id: "sebaq", label: "Sebaq", minPv: 5 },
+  // سباق — the race tile, offered only to pv≥5 clients
   { id: "trivia", label: "Trivia", minPv: 1, deprecated: true }
 ];
+var hostActivityForPv = (activity, pv) => activity === "options" && (pv ?? MIN_SUPPORTED_PV) < 6 ? "configuring" : activity;
+var COMEBACK_BONUS_MIN_PV = 7;
+var COMEBACK_EFFECTS = /* @__PURE__ */ new Set(["comebackBonus", "comebackOffer", "comebackDeclined"]);
+var effectsForPv = (effects, pv) => (pv ?? MIN_SUPPORTED_PV) >= COMEBACK_BONUS_MIN_PV ? effects : effects.filter((e) => !COMEBACK_EFFECTS.has(e.t));
 var gamesForPv = (pv) => GAMES.filter((g) => !g.deprecated && g.minPv <= pv);
 var gameIdForPv = (gameId, pv) => {
   const g = GAMES.find((x) => x.id === gameId);
@@ -77,7 +106,8 @@ var CHARACTER_IDS = ["m", "f"];
 var ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
 var UNSAFE_CHARS = /[\p{Cc}\u202A-\u202E\u2066-\u2069<>]/gu;
 var normalizeWesternDigits = (s) => s.replace(/[٠-٩۰-۹]/g, (d) => String("\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669".indexOf(d) >= 0 ? "\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669".indexOf(d) : "\u06F0\u06F1\u06F2\u06F3\u06F4\u06F5\u06F6\u06F7\u06F8\u06F9".indexOf(d)));
-var DisplayName = import_zod.z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform((s) => normalizeWesternDigits(s.replace(UNSAFE_CHARS, "")).trim()).refine((s) => s.length >= 1, "name is empty after sanitizing");
+var sanitizeName = (s) => normalizeWesternDigits(s.replace(UNSAFE_CHARS, "")).trim();
+var DisplayName = import_zod.z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform(sanitizeName).refine((s) => s.length >= 1, "name is empty after sanitizing");
 var RoomCode = import_zod.z.string().trim().toUpperCase().regex(new RegExp(`^[${ROOM_ALPHABET}]{${LIMITS.ROOM_CODE_LEN}}$`), "bad room code");
 var PlayerId = import_zod.z.string().max(40);
 var HelpType = import_zod.z.enum([
@@ -134,6 +164,42 @@ var ClientMsg = import_zod.z.discriminatedUnion("t", [
   import_zod.z.object({ t: import_zod.z.literal("kick"), playerId: PlayerId }),
   // Host's IN-PROGRESS category selection in the lobby — a live preview for waiting
   // players. Distinct from startGame.categoryIds, which COMMITS the board. Empty = cleared.
+  // ⚠️ AN EMPTY `categoryIds` IS A MEANINGFUL MESSAGE — DO NOT ADD `.min(1)`.
+  //
+  // The host sends `setCategories([])` the moment they press «التالي», before picking anything.
+  //
+  // ⚠️ THE THREE-STATE READING RECORDED IN a33f305 IS NOT DELIVERABLE ON THIS WIRE, AND A CLIENT
+  // WRITTEN TO IT WILL BE «FIXED» IN THE WRONG DIRECTION. It said:
+  //     absent            → still in the lobby
+  //     present but EMPTY → the host is choosing
+  //     non-empty         → the picks card
+  // The first state does not exist. `socket.ts` creates every room with `selectedCategoryIds: []`
+  // and `rooms.ts` serialises it on EVERY lobby frame, so a joiner's very first frame already carries
+  // `[]` — byte-identical to the host having pressed «التالي». QA measured it on prod (room J7UY,
+  // raw frames in geem-qa `findings/sebaq/race2.jsonl`): the joiner's lobby before and after the
+  // host's empty `setCategories` differ in nothing on this field. On iOS the visible result is that
+  // joiners read «يختار الفئات» the moment they land. (geem-server#118.)
+  //
+  // ⚠️ `hostActivity` IS THE CARRIER FOR «THE HOST IS CHOOSING» — it is the field built for this exact
+  // question and it distinguishes the state this one cannot: `'options'` (the host is on the settings
+  // surface) vs `'configuring'` vs `'idle'`. Read THAT for the waiting-screen line; read
+  // `selectedCategoryIds` only for WHICH categories, never for WHETHER the host has begun.
+  //
+  // What stays true from a33f305, and is still worth its test: an empty array must PARSE. Adding
+  // `.min(1)` would reject a message the client is right to send.
+  //
+  // Without it, joiners sat on «ناطرين … يبدأ اللعبة» for as long as the host browsed and only learned
+  // anything had happened when the FIRST pick landed (owner, 2026-08-26; fixed by the iOS desk).
+  //
+  // ⚠️ THE FAILURE IF SOMEONE TIGHTENS THIS IS SILENT AND LOOKS LIKE A CLIENT BUG. Nothing crashes:
+  // every joiner in every category game just goes back to «waiting to start» until the first pick.
+  // The relay would be rejecting a message the client is right to send, and the search would start on
+  // the client. Applies to صيدها, بالدور and سباق alike — they share one lobby.
+  // The host's verdict on a comeback offer (owner ruling 2026-08-27). `grant: false` is a real and
+  // expected outcome — «if he refuse then he will not get it» — and closes the offer with nothing.
+  // ⚠️ HOST-ONLY, and the relay enforces it. A trailing team that could grant its own bonus is not a
+  // bonus, it is a button that says «+100».
+  import_zod.z.object({ t: import_zod.z.literal("comebackDecide"), grant: import_zod.z.boolean() }),
   import_zod.z.object({ t: import_zod.z.literal("setCategories"), categoryIds: import_zod.z.array(import_zod.z.string().max(60)).max(12) }),
   // Host defines the lobby teams players can join (0–12; empty = disband back to the
   // one-team-per-player default). Resets picks that fall out of range.
@@ -150,10 +216,32 @@ var ClientMsg = import_zod.z.discriminatedUnion("t", [
   // `modeId` alone still works (pre-gs#49 clients); `game` is what lets a host announce a tile with
   // no modes (dama/ersimha), which `modeId` could never express. An incoherent pair (a mode that
   // doesn't belong to the game) is rejected with `bad_mode` rather than silently resolved.
+  // ── Sebaq slice (gameId 'sebaq', the RACE tile) ──
+  // ⚠️ THE SERVER JUDGES AND THE SERVER TIMES. The client sends which option was tapped and nothing
+  // else — no «correct», no elapsed ms. A client-reported time makes the best connection win, and a
+  // client-reported verdict makes the race unwinnable honestly.
+  import_zod.z.object({ t: import_zod.z.literal("sebaqAnswer"), optionIndex: import_zod.z.number().int().min(0).max(5) }),
+  // Rule 3: after ONE wrong answer the player chooses. `sebaqRetry` re-opens the SAME question for
+  // half points; `sebaqSkip` takes 0 and moves on. Two tiers only (rule 4) — a second wrong answer
+  // needs no message, it just ends the question.
+  import_zod.z.object({ t: import_zod.z.literal("sebaqRetry") }),
+  import_zod.z.object({ t: import_zod.z.literal("sebaqSkip") }),
   import_zod.z.object({ t: import_zod.z.literal("setMode"), game: import_zod.z.enum(GAME_IDS).optional(), modeId: import_zod.z.enum(MODE_IDS).optional() }),
   // Host signals it's busy configuring the game (categories/rounds/mode) so waiting players can show
   // a "host is setting up…" state instead of a frozen-looking lobby. 'idle' when the settings close.
-  import_zod.z.object({ t: import_zod.z.literal("hostActivity"), activity: import_zod.z.enum(["configuring", "idle"]) }),
+  // ⚠️ THREE VALUES SINCE 2026-08-26 (Options page, geem-coordination#24). The host's pre-game
+  // journey is Lobby → Options → Categories, and joiners route on this:
+  //     idle        → the lobby
+  //     options     → «how we play» — the per-game settings page, read-only for joiners
+  //     configuring → «… يختار الفئات» — the category picker
+  //
+  // ⚠️ THE RELAY MUST ACCEPT `options` BEFORE ANY CLIENT SENDS IT, which is why this ships ahead of
+  // the page: a new client sending it to an old relay is a `bad_message`, the activity stays whatever
+  // it was, and every joiner shows the wrong banner with nothing erroring.
+  import_zod.z.object({ t: import_zod.z.literal("hostActivity"), activity: import_zod.z.enum(["options", "configuring", "idle"]) }),
+  // ⚠️ AND IT IS ADAPTED ON THE WAY OUT (D-025), which is what makes it shippable without a
+  // coordinated release. `hostActivityForPv` below down-maps `options` → `configuring` for any client
+  // below pv6 — see there for the failure it prevents.
   // host game actions
   import_zod.z.object({
     t: import_zod.z.literal("startGame"),
@@ -266,9 +354,13 @@ var ClientMsg = import_zod.z.discriminatedUnion("t", [
   // Drawer passes on the served word (capped per draw-turn; relay serves a fresh one).
   import_zod.z.object({ t: import_zod.z.literal("skipWord") })
 ]);
+var SUBMISSION_STATUSES = ["pending", "accepted", "rejected"];
+var SUBMISSION_KINDS = ["new", "edit"];
+var REJECT_REASONS = ["duplicate", "unclear_answer", "not_family", "inaccurate", "too_narrow", "other"];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CHARACTER_IDS,
+  COMEBACK_BONUS_MIN_PV,
   ClientMsg,
   EMOTE_IDS,
   GAMES,
@@ -278,9 +370,15 @@ var ClientMsg = import_zod.z.discriminatedUnion("t", [
   MODES,
   MODE_IDS,
   PROTOCOL_VERSION,
+  REJECT_REASONS,
   ROOM_ALPHABET,
+  SUBMISSION_KINDS,
+  SUBMISSION_STATUSES,
+  effectsForPv,
   gameIdForPv,
   gamesForPv,
+  hostActivityForPv,
   modesForGame,
-  normalizeWesternDigits
+  normalizeWesternDigits,
+  sanitizeName
 });