@pplethai/cli 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pplethai/cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -26,7 +26,8 @@
     "@types/node": "^22.10.0",
     "esbuild": "^0.28.1",
     "typescript": "^5.8.0",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "yaml": "^2.9.1"
   },
   "engines": {
     "node": ">=22"

package/templates/golden-path/.dev.vars.example

@@ -3,11 +3,29 @@
 # settings below. `vite dev` and `wrangler dev` load `.dev.vars` automatically.
 
 # Which mock identity to sign in as locally. Defaults to "hq-staff".
-# Built-in personas: hq-staff, province-coordinator, platform-admin, delegate
+# Built-in personas: hq-staff, province-coordinator, platform-admin, delegate,
+# member (a party member with no role), unverified, kyc-pending,
+# kyc-verified-nonmember
 # (add your own in src/dev-personas.ts). Set to "none" to turn the bypass off
 # and exercise the real PPLE ID sign-in path locally.
+# On /.pple/registry/…, "none" or an unknown name sends no x-pple-identity
+# (the same as userToken: none). An unknown name does not fall back to
+# hq-staff on that path; /api still does.
 # DEV_PERSONA="province-coordinator"
 
+# Make offline callService return a platform refusal instead of a mock.
+# A code applies to every entry. provider/name=code applies to one entry
+# and wins over the global code. Separate several with commas.
+# invalid_app_key, not_listed, not_granted, needs_beta, user_token_invalid,
+# identity_unavailable, provider_unavailable, provider_timeout.
+# An unknown code is ignored.
+# DEV_REGISTRY_ERROR="needs_beta"
+# DEV_REGISTRY_ERROR="not_granted,shop/orders=provider_timeout"
+
+# Consumer slug reported on the emulated registry path. Defaults to
+# "dev-consumer". The entry id is dev-provider/<name>.
+# DEV_CONSUMER="brave-purple-lion"
+
 # Exercise the notification helper locally. These are normally injected by the
 # platform at deploy time.
 # NOTIFY_API_BASE="https://today.peoplesparty.or.th"

package/templates/golden-path/CLAUDE.md

@@ -31,12 +31,14 @@ which attach the PPLE ID bearer token. Same origin, so paths are relative
 Every `/api/*` request carries a PPLE ID bearer token; the Worker resolves it
 to an `Identity` (`src/auth.ts`, shape in `shared/api.ts`) with two faces:
 
-- **`actor`** — the real human clicking (`sub`, `name`, `mobile`). For audit
-  and display only.
-- **`effective`** — what they may do: `activeRole`, `eligibleRoles`,
-  `provinces` (scope), `extraRoles` (capabilities like `platform:admin`).
-  Under delegation `effective` holds the *supervisor's* values and
-  `effective.isDelegated` is true.
+- **`actor`** — the real human clicking (`sub`, `name`, `mobile`, `membership`).
+  For audit and display only. `membership` is `{ memberSince }` while the
+  party membership is active, and null otherwise.
+- **`effective`** — what they may do: `sub` (the person whose authority is
+  in effect), `activeRole`, `eligibleRoles`, `provinces` (scope), `extraRoles`
+  (capabilities like `platform:admin`). Under delegation these are the
+  *supervisor's* values, `effective.sub` is that person's PPLE ID sub (or null
+  when they have none), and `effective.isDelegated` is true.
 
 Where the token comes from:
 
@@ -47,9 +49,44 @@ Where the token comes from:
 - Locally (`npm run dev`) there is no login: the Worker signs you in as a mock
   **persona** (`DEV_PERSONA`, default `hq-staff` — see `src/dev-personas.ts`).
   To test a province-scoped feature use `DEV_PERSONA=province-coordinator`;
-  for delegation use `delegate`; for admin-only paths use `platform-admin`.
+  for delegation use `delegate`; for admin-only paths use `platform-admin`;
+  for a party member with no role use `member`.
   This bypass is gated on `import.meta.env.DEV`, so it is compiled out of the
   deployed Worker — there is nothing to set or unset for production.
+- A Service handler lives on `registry` in `src/index.ts`. Locally, curl
+  `/.pple/registry/<name>/…`. The dev wrapper sets `x-pple-consumer`
+  (`DEV_CONSUMER`, default `dev-consumer`), `x-pple-entry`
+  (`dev-provider/<name>`), and `x-pple-identity` from the active Persona.
+  `DEV_PERSONA=none` or an unknown persona name omits the Identity (as
+  `userToken: none` does) and does not fall back to `hq-staff` on this path.
+  Read the caller with `serviceCall(request)`. Tests call `callRegistry` from
+  `test/harness.ts`. An entry with no handler throws `registry handler missing`.
+  The wrapper is compiled out of the deployed Worker.
+- `callService` locally answers from `.pple/registry/<provider>/<name>/mocks/responses.json`
+  as the active persona (`x-pple-mock` names the entry). A `userToken: required`
+  entry called with no token is `user_token_invalid`. Nothing matched is
+  `no_mock` (404), dev-only, with a Thai message that names `pple registry`.
+  `DEV_REGISTRY_ERROR` (`<code>` or `<provider>/<name>=<code>`, commas) returns
+  that platform refusal instead. A persona added in `dev-personas.ts` only
+  hits cases that name no persona. `DEV_PERSONA=none` calls the real service.
+  Vitest uses the injected fetch and does not read the overlay. The overlay
+  glob keeps `.pple/registry` in its fixed base, and the whole path is
+  compiled out of the deployed Worker. `getLegalIdentity` still uses its own
+  offline answer.
+- `readDataset(env, entry, objectType, options)` reads a Dataset Object Type.
+  A collection page is `{ objects, next, sweptAt, snapshot }`; a singleton or
+  an id lookup is `{ object, sweptAt, snapshot }`. Pass `filter`, `sort` and
+  `limit`; pass `id` to look one object up; pass `follow: true` to walk
+  `next`. The user token is `options.userToken` and is sent only when set.
+  Platform refusals are `x-pple-error` (`not_found`, `invalid_query`,
+  `level_not_met`, and the same codes as `callService`). Locally it reads
+  `.pple/registry/<provider>/<name>/mocks/<objectType>.json` through the same
+  query rules and `passesLevel` against the active Persona. `sweptAt` is the
+  mock file's write time. A level whose `subs` list is missing, including
+  `subs: swept`, admits nobody offline. `DEV_REGISTRY_ERROR` and `no_mock`
+  work as they do for `callService`. `DEV_PERSONA=none` calls the real
+  service. Vitest uses the injected fetch. This path is compiled out of the
+  deployed Worker.
 
 ## Conventions
 
@@ -80,12 +117,13 @@ them through `/kyc` (`kycStartUrl`) if the app needs the number.
 Under delegation the Legal Identity is the actor's. If delegated use should
 be blocked, check `effective.isDelegated`.
 
-A **Legal Identity Grant** comes from a Platform Admin, and the app must be
-Beta or Live. Ask a Platform Admin. `getLegalIdentity` reasons:
-`not_configured` (bindings missing), `invalid_app_key`, `not_granted` (no
-grant, or Draft or retired), `not_verified`, `user_token_invalid`,
-`identity_not_enabled` (granted here, not allowlisted on pple-sso),
-`upstream_unavailable`.
+Legal Identity is the Private Platform Service `platform/legal-identity`, so
+the app needs a Use Grant: with the Builder's agreement, file
+`pple request use platform/legal-identity --reason "…"`. Calls flow at Beta
+or Live. `getLegalIdentity` reasons:
+`not_configured` (bindings missing), `invalid_app_key`, `not_granted`,
+`needs_beta` (the grant is held and the app is still Draft), `not_verified`,
+`user_token_invalid`, `upstream_unavailable`.
 
 Locally, try `DEV_PERSONA=unverified`, `kyc-pending`, or
 `kyc-verified-nonmember`. Member Personas are verified via membership and the

package/templates/golden-path/README.md

@@ -34,8 +34,33 @@ npm run dev        # http://localhost:5173
 full-stack dev server. No config files, no PPLE Today, no OAuth: you're signed
 in automatically as a mock **persona** (`hq-staff` by default). To develop as
 someone else, set `DEV_PERSONA` in `.dev.vars` (see `.dev.vars.example`) to
-`hq-staff`, `province-coordinator`, `platform-admin`, or `delegate` — or add
-your own in `src/dev-personas.ts`.
+`hq-staff`, `province-coordinator`, `platform-admin`, `delegate`, or `member` —
+or add your own in `src/dev-personas.ts`.
+
+`callService` on `npm run dev` answers from
+`.pple/registry/<provider>/<name>/mocks/responses.json` as that persona. A
+missing entry or route is `no_mock` (404) and names `pple registry`. Set
+`DEV_REGISTRY_ERROR` to rehearse a platform refusal such as `not_granted` or
+`provider_timeout`. `DEV_PERSONA=none` calls the real service. This path is
+compiled out of the deployed Worker.
+
+`readDataset` on `npm run dev` reads
+`.pple/registry/<provider>/<name>/mocks/<objectType>.json` the same way:
+filters, sort and pages run locally, and the active persona has to pass the
+Object Type's level. `sweptAt` is the time that mock file was written. A
+level that only names people, or a swept list, admits nobody offline — those
+lists are not in the overlay. `DEV_REGISTRY_ERROR` and `no_mock` work as they
+do for `callService`. `DEV_PERSONA=none` reads the real Dataset. This path is
+compiled out of the deployed Worker.
+
+To exercise a Service this app provides, curl
+`/.pple/registry/<name>/…` on the dev server. That path is delivered to
+`registry[name]` with the active Persona's Identity and a fake Consumer
+(`dev-consumer`, or `DEV_CONSUMER`). The entry id is `dev-provider/<name>`.
+`DEV_PERSONA=none`, or a persona name that is not defined, sends no
+Identity — the same as an entry that declares `userToken: none`. An unknown
+name does not fall back to `hq-staff` on this path. The wrapper is compiled
+out of the deployed Worker. Tests use `callRegistry` from `test/harness.ts`.
 
 Opened inside PPLE Today, the mini-app SDK signs the real user in from the
 launch URL; opened in a plain browser after deploy, the same SDK runs the

package/templates/golden-path/gitignore

@@ -9,3 +9,6 @@ dist/
 .cursor/rules/pple-platform.mdc
 .pple/rules.md
 .pple/guidance.json
+.pple/registry/
+.pple/registry.json
+.pple/registry-check.json

package/templates/golden-path/overlay-mtime.mjs

@@ -0,0 +1,30 @@
+// Embeds an overlay file's mtime for offline readDataset (ADR-0030).
+//
+// The Worker cannot stat a file. Vite replaces `import.meta.glob` of `?mtime`
+// with this module, so `sweptAt` is the time the overlay was written. The
+// glob sits in an `import.meta.env.DEV` branch and is absent from the
+// production build.
+
+import fs from "node:fs";
+
+export function overlayMtimePlugin() {
+  return {
+    name: "pple-overlay-mtime",
+    enforce: "pre",
+    load(id) {
+      const split = id.indexOf("?");
+      if (split === -1) return null;
+      const query = id.slice(split + 1);
+      const wants = query.split("&").some((part) => part === "mtime" || part.startsWith("mtime="));
+      if (!wants) return null;
+      const file = id.slice(0, split);
+      let iso = "";
+      try {
+        iso = fs.statSync(file).mtime.toISOString();
+      } catch {
+        iso = "";
+      }
+      return `export default ${JSON.stringify(iso)};`;
+    },
+  };
+}

package/templates/golden-path/package-lock.json

@@ -10,6 +10,7 @@
         "@pplethai/components": "^1.4.3",
         "@pplethai/pple-today-miniapp-sdk": "^0.1.4",
         "hono": "^4.12.30",
+        "lucide-react": "^0.469.0",
         "react": "^19.2.0",
         "react-dom": "^19.2.0",
         "react-hook-form": "^7.81.0",
@@ -25,7 +26,8 @@
         "typescript": "^5.8.0",
         "vite": "^8.1.5",
         "vitest": "^4.1.10",
-        "wrangler": "^4.112.0"
+        "wrangler": "^4.112.0",
+        "yaml": "^2.9.1"
       }
     },
     "node_modules/@cloudflare/kv-asset-handler": {
@@ -4246,6 +4248,22 @@
         }
       }
     },
+    "node_modules/yaml": {
+      "version": "2.9.1",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz",
+      "integrity": "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    },
     "node_modules/youch": {
       "version": "4.1.0-beta.10",
       "resolved": "https://registry.npmjs.org/youch/-/youch-4.1.0-beta.10.tgz",

package/templates/golden-path/package.json

@@ -6,7 +6,7 @@
   "scripts": {
     "predev": "wrangler d1 migrations apply DB --local",
     "dev": "vite dev",
-    "build": "vite build",
+    "build": "vite build && node scripts/assert-dev-compiled-out.mjs",
     "preview": "vite preview",
     "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.worker.json",
     "test": "vitest run",
@@ -35,6 +35,7 @@
     "typescript": "^5.8.0",
     "vite": "^8.1.5",
     "vitest": "^4.1.10",
-    "wrangler": "^4.112.0"
+    "wrangler": "^4.112.0",
+    "yaml": "^2.9.1"
   }
 }

package/templates/golden-path/scripts/assert-dev-compiled-out.mjs

@@ -0,0 +1,42 @@
+// The deployed Worker is dist/pple_app/index.js. Vite inlines
+// `import.meta.env.DEV` to false and drops the Persona bypass and the
+// offline registry wrapper (ADR-0011). Strings that exist only in those
+// modules must not survive. The client bundle is a different compile.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const bundle = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../dist/pple_app/index.js",
+);
+
+if (!fs.existsSync(bundle)) {
+  console.error(`production Worker bundle not found at ${bundle}`);
+  process.exit(1);
+}
+
+const source = fs.readFileSync(bundle, "utf8").replace(/\/\/# sourceMappingURL[\s\S]*$/, "");
+
+const forbidden = [
+  ["dev-hq-staff", "Persona bypass"],
+  ["Local Dev (HQ)", "Persona bypass"],
+  ["บุคคลทดสอบ ออฟไลน์", "offline Legal Identity"],
+  ["dev-consumer", "registry dev wrapper"],
+  ["DEV_CONSUMER", "registry dev wrapper"],
+  ["dev-provider", "registry dev wrapper"],
+  ["registry handler missing", "registry dev wrapper"],
+  ["x-pple-mock", "offline callService"],
+  ["../.pple/registry", "offline callService overlay glob"],
+  ["ไม่มีข้อมูลจำลอง", "offline callService no_mock"],
+];
+
+const found = forbidden.filter(([needle]) => source.includes(needle));
+if (found.length > 0) {
+  console.error(`production Worker still contains dev-only code (${bundle}):`);
+  for (const [needle, why] of found) console.error(`  ${JSON.stringify(needle)} (${why})`);
+  process.exit(1);
+}
+
+console.log("production Worker has no dev-only registry or Persona code");

package/templates/golden-path/shared/api.ts

@@ -8,8 +8,10 @@ import { z } from "zod";
  * The signed-in caller, as the Worker resolves it from the PPLE ID token
  * (src/auth.ts). Two faces:
  *
- * - `actor` — the real human clicking. Use for audit and display only.
- * - `effective` — what they may do. Gate every authorization decision on this,
+ * - `actor` — the real human clicking (`sub`, name, mobile, KYC Status,
+ *   party membership). Use for audit and display only.
+ * - `effective` — what they may do, including `sub` of the person whose
+ *   authority is in effect. Gate every authorization decision on this,
  *   never on `actor`. Under Delegation these are the supervisor's values and
  *   `isDelegated` is true. See docs/adr/0012 and CONTEXT.md.
  */
@@ -28,6 +30,16 @@ export const KycStatusSchema = z.object({
 });
 export type KycStatus = z.infer<typeof KycStatusSchema>;
 
+/**
+ * Active party membership as the Identity carries it. `memberSince` is the
+ * ISO date (`YYYY-MM-DD`) PPLE ID reports. The actor field is null when the
+ * person is not an active member, or the lookup failed.
+ */
+export const MembershipSchema = z.object({
+  memberSince: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+});
+export type Membership = z.infer<typeof MembershipSchema>;
+
 export const ActorSchema = z.object({
   sub: z.string(),
   name: z.string().nullable(),
@@ -35,12 +47,23 @@ export const ActorSchema = z.object({
   mobile: z.string().nullable(),
   /** Never copied onto `effective`. See KycStatusSchema. */
   kyc: KycStatusSchema,
+  /**
+   * The human's party membership. Never copied onto `effective`: a delegate
+   * does not inherit a supervisor's membership. A lookup error is null.
+   */
+  membership: MembershipSchema.nullable(),
 });
 export type Actor = z.infer<typeof ActorSchema>;
 
 export const EffectiveSchema = z.object({
   /** True ⇒ the values below are borrowed from a supervisor (see Actor). */
   isDelegated: z.boolean(),
+  /**
+   * PPLE ID sub of the person whose authority is in effect. The actor's own
+   * sub when nobody is delegating. Under Delegation, the supervisor's Zitadel
+   * sub, or null when PPLE ID has none. Null matches no custom `subs`.
+   */
+  sub: z.string().min(1).nullable(),
   /** The Role in play now (one of `eligibleRoles`), e.g. "hq", "province". */
   activeRole: z.string(),
   eligibleRoles: z.array(z.string()),

package/templates/golden-path/src/auth.ts

@@ -10,7 +10,8 @@
 //   • actor     — the real human clicking (audit/display only)
 //   • effective — what they may do (gate authorization on this)
 // Under Delegation, effective.* are the supervisor's and effective.isDelegated
-// is true, while actor stays the delegate. See docs/adr/0012.
+// is true, while actor stays the delegate. effective.sub is the PPLE ID sub
+// of the person whose authority is in effect. See docs/adr/0012.
 import type { Identity } from "../shared/api";
 import { resolveDevPersona } from "./dev-personas";
 
@@ -74,6 +75,11 @@ interface RawPerson {
   id?: number;
   role?: string;
   mobile?: string;
+  /**
+   * The person's Zitadel user id, which is their PPLE ID sub. Read only for
+   * the supervisor under Delegation. Never `sso_user_id`.
+   */
+  zitadel_user_id?: unknown;
   metadata?: { ad?: { extra_roles?: unknown; is_province_coordinator?: unknown } };
 }
 
@@ -97,9 +103,62 @@ interface RawUserInfo {
   name?: string;
   /** KYC Status of the human who logged in. Absent until PPLE ID sends it. */
   kyc?: RawKyc;
+  /**
+   * Party membership of the logged-in human, beside `ad` and `kyc`.
+   * PPLE ID sends an object or null. See membershipOf.
+   */
+  membership?: unknown;
   ad?: RawAd;
 }
 
+/** `YYYY-MM-DD`, the shape of userinfo `membership.memberSince`. */
+const MEMBER_SINCE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Reduce userinfo `membership` to `{ memberSince }` or null.
+ *
+ * PPLE ID sends `{ type, memberSince, registeredAddress }` only while the
+ * membership is legally active, looked up by the logged-in human's phone.
+ * A lookup error arrives as null. The Identity keeps the date and drops the
+ * address. A missing or odd value is null, so it cannot pass `member`.
+ */
+function membershipOf(value: unknown): Identity["actor"]["membership"] {
+  if (value === null || value === undefined || typeof value !== "object") return null;
+  const memberSince = (value as { memberSince?: unknown }).memberSince;
+  if (typeof memberSince !== "string" || !MEMBER_SINCE.test(memberSince)) return null;
+  return { memberSince };
+}
+
+/** Zitadel user ids are decimal strings. Anything else is not a PPLE ID sub. */
+const ZITADEL_SUB = /^\d+$/;
+
+/**
+ * `effective.sub` (ADR-0028, #266).
+ *
+ * Not delegated (`isDelegated` false): the Actor's `sub` from the token. It
+ * is never read from `ad`. PPLE ID falls back silently to the logged-in row
+ * when the supervisor row is missing, and that reads as not delegated.
+ *
+ * Delegated: `ad.user` is the supervisor only when the logged-in human's role
+ * is `delegate`. The supervisor's sub is `ad.user.zitadel_user_id`.
+ * `sso_user_id` is legacy (a Supabase UUID or null) and is never read. Any
+ * other delegated shape, or a missing, null, or non-Zitadel id, is null. It
+ * is never the Actor's sub, because `effective` is someone else's authority
+ * here. Null matches no custom `subs`.
+ */
+function effectiveSub(
+  actorSub: string,
+  isDelegated: boolean,
+  user: RawPerson | undefined,
+  actual: RawPerson | undefined,
+): string | null {
+  if (!isDelegated) return actorSub;
+  if (actual?.role !== "delegate") return null;
+  const zitadel = user?.zitadel_user_id;
+  if (typeof zitadel !== "string" || !ZITADEL_SUB.test(zitadel)) return null;
+  return zitadel;
+}
+
 function stringArray(value: unknown): string[] {
   return Array.isArray(value)
     ? value.filter((v): v is string => typeof v === "string")
@@ -137,24 +196,30 @@ function toIdentity(body: RawUserInfo): Identity {
   const effectivePerson = ad?.user;
   // When nobody is delegating, `actualPpleUser` mirrors `user`.
   const actualPerson = ad?.actualPpleUser ?? effectivePerson;
+  const isDelegated =
+    effectivePerson?.id !== undefined &&
+    actualPerson?.id !== undefined &&
+    effectivePerson.id !== actualPerson.id;
   const activeRole = ad?.activeRole ?? effectivePerson?.role ?? "";
   const eligibleRoles = stringArray(ad?.eligibleRoles);
+  // Top-level `sub` is the OIDC subject of the human who logged in.
+  const actorSub = body.sub as string;
 
   return {
     actor: {
-      // Top-level `sub` is the OIDC subject of the human who logged in.
-      sub: body.sub as string,
+      sub: actorSub,
       name: body.name ?? null,
       mobile: actualPerson?.mobile ?? null,
       // The human's own KYC Status. A delegated session still reports the
       // actor's, never the supervisor's, and effective never carries it.
       kyc: kycOf(body.kyc),
+      // The human's own membership, likewise. Top-level userinfo, not `ad.user`
+      // (under Delegation `ad.user` is the supervisor).
+      membership: membershipOf(body.membership),
     },
     effective: {
-      isDelegated:
-        effectivePerson?.id !== undefined &&
-        actualPerson?.id !== undefined &&
-        effectivePerson.id !== actualPerson.id,
+      isDelegated,
+      sub: effectiveSub(actorSub, isDelegated, effectivePerson, ad?.actualPpleUser),
       activeRole,
       eligibleRoles:
         eligibleRoles.length > 0 ? eligibleRoles : activeRole ? [activeRole] : [],

package/templates/golden-path/src/call-service.ts

@@ -0,0 +1,140 @@
+// A Consumer's call to a Registry Service (ADR-0024). The Builder names the
+// entry and the path tail. This module adds the services address, the App
+// Key, and — only when the caller passes one — the user token. The Builder
+// never sets those.
+//
+// Under `npm run dev`, while `DEV_PERSONA` is not `"none"`, the answer comes
+// from the workspace overlay (ADR-0026, `dev-call-service.ts`). That branch
+// is compiled out of the production build. `getLegalIdentity` still uses its
+// built-in Persona answer before it calls this. Under vitest the fetch is
+// the one the test injected: this module does not read the overlay, which
+// CI does not have.
+
+import { answerOfflineCall } from "./dev-call-service";
+
+export const PLATFORM_ERROR_HEADER = "x-pple-error";
+
+/**
+ * Platform refusals, in the order a caller meets them.
+ * The first eight are ADR-0024 (a Service call). The last four are ADR-0030
+ * (a Dataset read) and are not part of the Service check order.
+ */
+export const PLATFORM_ERROR_CODES = [
+  "invalid_app_key",
+  "not_listed",
+  "not_granted",
+  "needs_beta",
+  "user_token_invalid",
+  "identity_unavailable",
+  "provider_unavailable",
+  "provider_timeout",
+  "method_not_allowed",
+  "not_found",
+  "invalid_query",
+  "level_not_met",
+] as const;
+
+export type PlatformErrorCode = (typeof PLATFORM_ERROR_CODES)[number];
+
+const PLATFORM_ERROR_SET: ReadonlySet<string> = new Set(PLATFORM_ERROR_CODES);
+
+const USER_TOKEN_HEADER = "x-pple-user-token";
+
+export interface CallServiceEnv {
+  PPLE_SERVICES_URL?: string;
+  PPLE_APP_KEY?: string;
+  /** `"none"` uses the real service. Anything else, under `npm run dev`, uses the overlay. */
+  DEV_PERSONA?: string;
+  /**
+   * Offline only. `<code>` for every entry, or `<provider>/<name>=<code>`,
+   * comma-separated. A per-entry code wins. Unknown codes are ignored.
+   */
+  DEV_REGISTRY_ERROR?: string;
+}
+
+export interface CallServiceOptions {
+  /** End-user PPLE ID token. Sent as `x-pple-user-token` only when set. */
+  userToken?: string;
+  /**
+   * Test seam. Under vitest this is required: `callService` does not fall
+   * back to `globalThis.fetch`. Production omits it.
+   */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * `GET`/`POST`/… `services.<domain>/<provider>/<name>/<path>`.
+ *
+ * `path` `""` is the entry root. A path without a leading `/` or `?` gains
+ * one `/`. The App Key is always `Authorization: Bearer`. A `userToken` is
+ * the only way the user token is sent; a token on `init` is dropped.
+ *
+ * The returned `Response` is the platform's or the Provider's, unchanged,
+ * except under `npm run dev` (see above), where it is a mock or a dev refusal.
+ * Tell a platform refusal apart from a Provider response with `platformError`.
+ * `no_mock` is dev-only and is not a platform code.
+ */
+export async function callService(
+  env: CallServiceEnv,
+  entry: string,
+  path: string,
+  init: RequestInit = {},
+  options: CallServiceOptions = {},
+): Promise<Response> {
+  if (!/^[^/\s]+\/[^/\s]+$/.test(entry)) {
+    throw new Error('callService entry must be "<provider>/<name>"');
+  }
+
+  // `import.meta.env.DEV` is false in the production build, so this branch
+  // and `dev-call-service.ts` are absent from the deployed Worker. Vitest
+  // keeps the injected fetch even when a Persona is set.
+  if (import.meta.env.DEV && env.DEV_PERSONA !== "none" && !underVitest()) {
+    return answerOfflineCall(env, entry, path, init, options);
+  }
+
+  const fetchImpl = resolveFetch(options.fetchImpl);
+  if (!env.PPLE_SERVICES_URL || !env.PPLE_APP_KEY) {
+    throw new Error("callService needs PPLE_SERVICES_URL and PPLE_APP_KEY");
+  }
+
+  const headers = new Headers(init.headers);
+  headers.set("authorization", `Bearer ${env.PPLE_APP_KEY}`);
+  if (options.userToken !== undefined) headers.set(USER_TOKEN_HEADER, options.userToken);
+  else headers.delete(USER_TOKEN_HEADER);
+
+  return fetchImpl(serviceUrl(env.PPLE_SERVICES_URL, entry, path), { ...init, headers });
+}
+
+/**
+ * The platform refusal code on `response`, read from `x-pple-error`.
+ *
+ * Null when the header is absent or names a code outside ADR-0024 and
+ * ADR-0030. A null from an absent header means the Provider answered.
+ * `no_mock` is dev-only and stays null here. Callers that must not treat an
+ * unknown code as a Provider response check the header itself.
+ */
+export function platformError(response: Response): PlatformErrorCode | null {
+  const code = response.headers.get(PLATFORM_ERROR_HEADER);
+  if (code === null || !PLATFORM_ERROR_SET.has(code)) return null;
+  return code as PlatformErrorCode;
+}
+
+function serviceUrl(base: string, entry: string, path: string): string {
+  const root = `${base.replace(/\/+$/, "")}/${entry}`;
+  if (path === "") return root;
+  if (path.startsWith("/") || path.startsWith("?")) return `${root}${path}`;
+  return `${root}/${path}`;
+}
+
+function resolveFetch(fetchImpl: typeof fetch | undefined): typeof fetch {
+  if (fetchImpl) return fetchImpl;
+  if (underVitest()) {
+    throw new Error("callService under vitest uses the injected fetch");
+  }
+  return globalThis.fetch.bind(globalThis);
+}
+
+function underVitest(): boolean {
+  const flag = import.meta.env.VITEST;
+  return import.meta.env.MODE === "test" || flag === true || flag === "true";
+}