@econ-v1/domain 6.7.0 → 6.10.0

package/dist/services/wifi-provisioning-service.d.ts

@@ -0,0 +1,146 @@
+export class WifiProvisioningService {
+    /**
+     * @param {WifiProvisioningServiceOptions} options
+     */
+    constructor(options: WifiProvisioningServiceOptions);
+    /**
+     * @param {() => boolean} [shouldContinue]
+     * @returns {Promise<WifiReconnectOutcome>}
+     */
+    awaitReconnect(shouldContinue?: () => boolean): Promise<WifiReconnectOutcome>;
+    /**
+     * Whether the node is ALREADY joined to a home network. Asked once at flow entry so a person
+     * who configured Wi-Fi on the node's own captive portal is never marched through the
+     * credential steps a second time — resubmitting working credentials is not idempotent on the
+     * node side (the join tears down and re-adds the connection) and a handshake flake in that
+     * window strands the node back in setup AP mode. The wire values are node-server's
+     * `http_status` PascalCase strings; only an explicit `"Connected"` counts.
+     * @returns {Promise<WifiStatusOutcome>}
+     */
+    status(): Promise<WifiStatusOutcome>;
+    /** Lists what the node's radio can currently see. A failure is a first-class outcome, not a
+     * throw: step 4 stays on screen and offers "Scan again".
+     * @returns {Promise<WifiScanOutcome>}
+     */
+    scan(): Promise<WifiScanOutcome>;
+    /**
+     * Hands the credentials to the node exactly once. `secret === undefined` means an open
+     * network, in which case the `password` key is omitted rather than sent as an empty string —
+     * the node validates length 8-63 whenever the field is present.
+     * @param {string} ssid
+     * @param {string | undefined} secret
+     * @returns {Promise<WifiConfigureOutcome>}
+     */
+    configure(ssid: string, secret: string | undefined): Promise<WifiConfigureOutcome>;
+    /**
+     * Watches one configure operation across the network handoff. See the class comment: a
+     * thrown poll is EXPECTED and means "keep waiting".
+     *
+     * `deadline` is an absolute epoch-millisecond value from the same clock as `now`, supplied by
+     * the caller so a resumed flow can keep the ORIGINAL deadline rather than restarting it.
+     * @param {string} operationId
+     * @param {number} deadline
+     * @param {() => void} [onTransportLost]
+     * @returns {Promise<WifiHandoffOutcome>}
+     */
+    awaitHandoff(operationId: string, deadline: number, onTransportLost?: () => void): Promise<WifiHandoffOutcome>;
+    #private;
+}
+export type DelayPort = import("@econ-v1/ports").DelayPort;
+export type HomeNodeClient = import("@econ-v1/ports").HomeNodeClient;
+/**
+ * The node's Wi-Fi provisioning surface, expressed as three operations with CLOSED outcome
+ * unions (design §10). Nothing here throws at its caller and nothing here returns node text:
+ * `OnboardingFlowService` turns these outcomes into `OnboardingReasonCode`s, and the UI turns
+ * those into copy. A raw `DomainError.message` reaching a subscriber would be both a leak and
+ * an unreviewable string in the product.
+ *
+ * THE CENTRAL DIFFICULTY is `awaitHandoff()`. Between `configure()` and the node reporting
+ * `Connected`, the node LEAVES its own access point and joins the home network — the browser
+ * that issued the request is on that access point, so the poll *is expected to fail*, possibly
+ * for the entire operation. A thrown request here therefore means "keep waiting", not "it
+ * broke"; only three things end the wait:
+ *
+ *   - the node answering `Connected`      -> "connected"           (it came back, on the LAN)
+ *   - the node answering `Failed`         -> "credentials-rejected" (it came back to say no)
+ *   - the deadline passing                -> "unreachable"          (step 7's manual way back)
+ *
+ * `Failed` is the ONLY signal that distinguishes a wrong password from a normal handoff, which
+ * is why it must not be collapsed into the generic failure branch: collapsing it would send a
+ * person who mistyped their password to "walk back to your node" instead of to the keyboard.
+ *
+ * The status strings are the node's, verified against
+ * `core/adapters-network/src/http/server/wifi.rs::http_operation_status`, which maps its
+ * internal states onto exactly `"Connected"` / `"Failed"` / `"Connecting"` / `"Pending"`.
+ * (The design doc's "Completed" is wrong; the wire value is "Connected".)
+ *
+ * SECURITY: `configure()` takes the secret as an argument and forwards it in a single request.
+ * It is never assigned to a field, never returned, never logged, and never included in an
+ * outcome — `WifiConfigureOutcome` has no field it could occupy.
+ */
+export type WifiProvisioningSecurity = "open" | "wep" | "wpa2" | "wpa3";
+export type WifiScanOutcome = {
+    readonly kind: "scanned";
+    readonly networks: readonly WifiProvisioningNetwork[];
+} | {
+    readonly kind: "scan-failed";
+};
+export type WifiConfigureOutcome = {
+    readonly kind: "accepted";
+    readonly operationId: string;
+} | {
+    readonly kind: "credentials-rejected";
+} | {
+    readonly kind: "unreachable";
+};
+export type WifiHandoffOutcome = "connected" | "credentials-rejected" | "unreachable";
+export type WifiReconnectOutcome = "connected" | "superseded";
+/**
+ * What the node's radio is doing RIGHT NOW, asked once at flow entry. `connected` carries the
+ * joined SSID so the flow can show which network needs no credentials. `unreachable` collapses
+ * every failure — a flow that cannot ask simply walks the ordinary Wi-Fi steps.
+ */
+export type WifiStatusOutcome = {
+    readonly kind: "connected";
+    readonly ssid: string;
+} | {
+    readonly kind: "not-connected";
+} | {
+    readonly kind: "unreachable";
+};
+export type WifiProvisioningNetwork = {
+    security: WifiProvisioningSecurity;
+    /**
+     * 0-100 signal quality. dBm never crosses this boundary.
+     */
+    signal: number;
+    ssid: string;
+};
+export type WifiProvisioningServiceOptions = {
+    delay: Pick<DelayPort, "wait">;
+    node: Pick<HomeNodeClient, "invoke">;
+    /**
+     * Epoch milliseconds. Injected so the deadline is testable and domain owns no clock.
+     */
+    now: () => number;
+};
+export type WifiScanRowWire = {
+    security?: unknown;
+    signal_quality_percent?: unknown;
+    ssid?: unknown;
+};
+export type WifiScanWire = {
+    networks?: readonly WifiScanRowWire[];
+};
+export type WifiConfigureWire = {
+    operation_id?: unknown;
+    success?: unknown;
+};
+export type WifiOperationStatusWire = {
+    status?: unknown;
+};
+export type WifiStatusWire = {
+    connection_status?: unknown;
+    current_ssid?: unknown;
+};
+//# sourceMappingURL=wifi-provisioning-service.d.ts.map

package/dist/services/wifi-provisioning-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wifi-provisioning-service.d.ts","sourceRoot":"","sources":["../../src/services/wifi-provisioning-service.js"],"names":[],"mappings":"AAOA;IAyBE;;OAEG;IACH,qBAFW,8BAA8B,EAMxC;IA/BD;;;OAGG;IACH,gCAHW,MAAM,OAAO,GACX,OAAO,CAAC,oBAAoB,CAAC,CASzC;IAqBD;;;;;;;;OAQG;IACH,UAFa,OAAO,CAAC,iBAAiB,CAAC,CAiBtC;IACD;;;OAGG;IACH,QAFa,OAAO,CAAC,eAAe,CAAC,CAwBpC;IACD;;;;;;;OAOG;IACH,gBAJW,MAAM,UACN,MAAM,GAAG,SAAS,GAChB,OAAO,CAAC,oBAAoB,CAAC,CA+BzC;IACD;;;;;;;;;;OAUG;IACH,0BALW,MAAM,YACN,MAAM,oBACN,MAAM,IAAI,GACR,OAAO,CAAC,kBAAkB,CAAC,CA2BvC;;CACF;wBAtKa,OAAO,gBAAgB,EAAE,SAAS;6BAClC,OAAO,gBAAgB,EAAE,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCA2NxC,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM;8BAG9B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAA;CAAE,GAC3F;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE;mCAGxB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,GACzC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE;iCAEzB,WAAW,GAAG,sBAAsB,GAAG,aAAa;mCACpD,WAAW,GAAG,YAAY;;;;;;gCAIzB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE;;cAIzB,wBAAwB;;;;YACxB,MAAM;UACN,MAAM;;;WAIN,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC;UACvB,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC;;;;SAC9B,MAAM,MAAM;;;eAIZ,OAAO;6BACP,OAAO;WACP,OAAO;;;eAIP,SAAS,eAAe,EAAE;;;mBAI1B,OAAO;cACP,OAAO;;;aAIP,OAAO;;;wBAIP,OAAO;mBACP,OAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@econ-v1/domain",
-  "version": "6.7.0",
+  "version": "6.10.0",
   "description": "Platform-neutral domain contracts and errors for Node clients",
   "license": "MIT OR Apache-2.0",
   "author": "Node contributors",
@@ -17,31 +17,37 @@
     "node-client",
     "domain",
     "contracts",
-    "typescript"
+    "javascript",
+    "jsdoc"
   ],
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./src/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "rm -rf dist && tsc -b --pretty false",
+    "build": "rm -rf dist && tsc -p tsconfig.publish.json --pretty false",
+    "check": "node ../scripts/check-negative-type-contracts.mjs --config jsconfig.json",
+    "check:declarations": "node ../scripts/check-package-api-parity.mjs && node ../scripts/check-domain-declaration-shape.mjs",
     "lint": "eslint src",
-    "prepack": "npm run build",
+    "prepack": "npm run build && node ../scripts/check-public-package.mjs .",
     "test": "vitest run --passWithNoTests",
-    "type-check": "tsc -b --pretty false"
+    "check:consumer": "node ../scripts/check-negative-type-contracts.mjs --config jsconfig.consumer.json",
+    "type-check": "yarn run check && yarn check:declarations && yarn check:consumer"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.3"
   },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
+      "import": "./src/index.js",
+      "default": "./src/index.js"
     }
   },
   "files": [
+    "src/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
-    "dist/**/*.js",
-    "dist/**/*.js.map",
-    "!dist/**/*.test.*"
+    "!src/**/*.test.js"
   ],
   "sideEffects": false,
   "engines": {
@@ -51,6 +57,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@econ-v1/ports": "6.7.0"
+    "@econ-v1/ports": "6.10.0"
   }
 }

package/src/errors/index.js

@@ -0,0 +1,126 @@
+// @ts-check
+
+/**
+ * @typedef {import("../models/index.js").JsonObject} JsonObject
+ */
+/**
+ * @typedef {(typeof DOMAIN_ERROR_CODES)[number]} DomainErrorCode
+ */
+/**
+ * @typedef {(typeof SYNC_ERROR_CODES)[number]} SyncErrorCode
+ */
+/**
+ * @typedef {(typeof TRANSPORT_ERROR_CODES)[number]} TransportErrorCode
+ */
+/**
+ * @template {string} TCode
+ * @typedef {{ readonly code: TCode; readonly details?: JsonObject; readonly message: string; }} ErrorOptions
+ */
+/**
+ * @template {string} TKind
+ * @template {string} TCode
+ * @typedef {{ readonly code: TCode; readonly details?: JsonObject; readonly kind: TKind; readonly message: string; }} SerializableError
+ */
+/**
+ * @typedef {DomainError | SyncError | TransportError} ClientError
+ */
+/**
+ * @typedef {| SerializableError<"domain", DomainErrorCode> | SerializableError<"sync", SyncErrorCode> | SerializableError<"transport", TransportErrorCode>} SerializableClientError
+ */
+/** @type {readonly ["access-code-invalid", "capability_not_declared", "code-already-bound", "conflict", "invalid_request", "not_found", "stage_composition_not_enabled", "unauthorized", "unsupported_query", "validation_failed"]} */
+export const DOMAIN_ERROR_CODES = [
+    // Onboarding access-code rail (2026-08-10 design): the two envelope codes
+    // `onboarding-prepare` refuses with when a code-active node rejects a device's claim
+    // attempt — see `client/adapters-web/src/network/envelope-error-mapping.js`'s
+    // `CODE_ALREADY_BOUND`/`ACCESS_CODE_INVALID`/`ACCESS_CODE_REQUIRED` mapping and
+    // `OnboardingFlowService`'s matching `OnboardingFlowReasonCode` members.
+    "access-code-invalid",
+    "capability_not_declared",
+    "code-already-bound",
+    "conflict",
+    "invalid_request",
+    "not_found",
+    "stage_composition_not_enabled",
+    "unauthorized",
+    "unsupported_query",
+    "validation_failed",
+];
+/** @type {readonly ["outbox_delivery_failed", "sync_conflict", "sync_terminal_failure"]} */
+export const SYNC_ERROR_CODES = ["outbox_delivery_failed", "sync_conflict", "sync_terminal_failure"];
+/** @type {readonly ["connection_lost", "offline", "unavailable"]} */
+export const TRANSPORT_ERROR_CODES = ["connection_lost", "offline", "unavailable"];
+/**
+ * @abstract
+ * @template {string} TKind
+ * @template {string} TCode
+ * @extends {Error}
+ */
+class SerializableClientErrorBase extends Error {
+    /**
+   * @readonly
+   * @type {TKind}
+   */
+    kind;
+    /**
+   * @readonly
+   * @type {TCode}
+   */
+    code;
+    /**
+   * @readonly
+   * @type {JsonObject | undefined}
+   */
+    details;
+    /**
+   * @protected
+   * @param {TKind} kind
+   * @param {ErrorOptions<TCode>} options
+   */
+    constructor(kind, options) {
+        super(options.message);
+        this.kind = kind;
+        this.code = options.code;
+        this.details = options.details;
+    }
+    /**
+   * @returns {SerializableError<TKind, TCode>}
+   */
+    toJSON() {
+        return this.details === undefined
+            ? { code: this.code, kind: this.kind, message: this.message }
+            : { code: this.code, details: this.details, kind: this.kind, message: this.message };
+    }
+}
+/**
+ * @extends {SerializableClientErrorBase<"domain", DomainErrorCode>}
+ */
+export class DomainError extends SerializableClientErrorBase {
+    /**
+   * @param {ErrorOptions<DomainErrorCode>} options
+   */
+    constructor(options) {
+        super("domain", options);
+    }
+}
+/**
+ * @extends {SerializableClientErrorBase<"sync", SyncErrorCode>}
+ */
+export class SyncError extends SerializableClientErrorBase {
+    /**
+   * @param {ErrorOptions<SyncErrorCode>} options
+   */
+    constructor(options) {
+        super("sync", options);
+    }
+}
+/**
+ * @extends {SerializableClientErrorBase<"transport", TransportErrorCode>}
+ */
+export class TransportError extends SerializableClientErrorBase {
+    /**
+   * @param {ErrorOptions<TransportErrorCode>} options
+   */
+    constructor(options) {
+        super("transport", options);
+    }
+}

package/src/events/index.js

@@ -0,0 +1,124 @@
+// @ts-check
+
+/** @typedef {import("@econ-v1/ports").TransportState} TransportState */
+/** @typedef {import("@econ-v1/ports").OfflineIdentityScope} OfflineIdentityScope */
+/** @typedef {import("@econ-v1/ports").OfflineStageReadiness} OfflineStageReadiness */
+/** @typedef {import("../models/json.js").JsonObject} JsonObject */
+/** @typedef {import("../models/outbox.js").OutboxIntent} OutboxIntent */
+/** @typedef {`${string}.v${number}`} QueryName */
+/** @typedef {`app.${string}`} AppEventType */
+/** @typedef {{ readonly data: JsonObject, readonly instance?: string, readonly resource: string, readonly type: string }} AppEventPayload */
+/** @typedef {{ readonly anchorSession: string, readonly argsDelta?: string, readonly callId?: string, readonly callIndex?: number, readonly agentName?: string, readonly kind: "room.turn_started" | "turn.completed" | "turn.delta" | "turn.failed" | "turn.tool_delta" | "work.delta", readonly runId?: string, readonly reason?: string, readonly responderName?: string, readonly responderSlug?: string, readonly roomId: string, readonly text?: string, readonly toolName?: string }} RoomTurnStreamPayload */
+/** @typedef {{ readonly closedAt?: string, readonly jobId: string, readonly openedAt: string, readonly openedBySeq?: number, readonly origin: "scheduled" | "user", readonly pendingArrivals: number, readonly queueCount: number, readonly roomId: string, readonly status: "aborted" | "capped" | "done" | "open", readonly stepCount: number, readonly turnsUsed: number }} RoomJobSummary */
+/** @typedef {{ readonly actor: { readonly kind: "orchestrator" | "specialist", readonly name?: string, readonly slug?: string }, readonly detail: string, readonly kind: string, readonly outcome?: string, readonly runId?: string, readonly seq?: number, readonly stepId: string, readonly ts: string }} RoomJobStep */
+/** @typedef {{ readonly job: RoomJobSummary, readonly kind: "job" | "job_step", readonly roomId: string, readonly step?: RoomJobStep }} RoomJobStreamPayload */
+
+const APP_EVENT_RESOURCE_PATTERN = /^[a-z][a-z0-9_]*(?:-[a-z0-9_]+)*$/u;
+const APP_EVENT_INSTANCE_PATTERN = /^[^#\s]+$/u;
+
+/**
+ * @param {string} value
+ * @returns {{ instance?: string, resource: string } | undefined}
+ */
+function parseAppEventType(value) {
+  if (!value.startsWith("app.")) return undefined;
+  const rest = value.slice("app.".length);
+  const separator = rest.indexOf("#");
+  if (separator === -1) {
+    return APP_EVENT_RESOURCE_PATTERN.test(rest)
+      ? { resource: rest }
+      : undefined;
+  }
+  const resource = rest.slice(0, separator);
+  const instance = rest.slice(separator + 1);
+  if (
+    !APP_EVENT_RESOURCE_PATTERN.test(resource) ||
+    !APP_EVENT_INSTANCE_PATTERN.test(instance)
+  ) {
+    return undefined;
+  }
+  return { instance, resource };
+}
+
+/** @type {readonly ["transport.state-changed", "stage.catalog-invalidated", "stage.registry-changed", "query.invalidated", "outbox.state-changed", "domain.entity-changed", "sync.delta-applied", "client-storage.state-changed", "offline.stage-readiness-changed", "offline.identity-invalidated", "app.data.changed", "app.data.committed", "onboarding.flow-changed", "device-cleanup.changed", "room.turn-stream", "room.job-stream"]} */
+export const KERNEL_EVENT_TYPES = [
+  "transport.state-changed",
+  "stage.catalog-invalidated",
+  "stage.registry-changed",
+  "query.invalidated",
+  "outbox.state-changed",
+  "domain.entity-changed",
+  "sync.delta-applied",
+  "client-storage.state-changed",
+  "offline.stage-readiness-changed",
+  "offline.identity-invalidated",
+  "app.data.changed",
+  "app.data.committed",
+  "onboarding.flow-changed",
+  "device-cleanup.changed",
+  "room.turn-stream",
+  "room.job-stream",
+];
+
+/** @typedef {(typeof KERNEL_EVENT_TYPES)[number]} CoreKernelEventType */
+/** @typedef {AppEventType | CoreKernelEventType} KernelEventType */
+/** @typedef {{ readonly "client-storage.state-changed": { readonly code?: string, readonly message?: string, readonly status: "ready" | "recovery-required" | "starting" }, readonly "offline.stage-readiness-changed": { readonly readiness: OfflineStageReadiness }, readonly "offline.identity-invalidated": { readonly scope: OfflineIdentityScope }, readonly "app.data.changed": { readonly appName: string, readonly cursor: string, readonly revision: string, readonly stream: string }, readonly "app.data.committed": { readonly appName: string, readonly cursor: string, readonly revision: string, readonly stream: string }, readonly "device-cleanup.changed": { readonly state?: string }, readonly "domain.entity-changed": { readonly action: "created" | "deleted" | "updated", readonly entityId: string, readonly entityType: string }, readonly "onboarding.flow-changed": { readonly stepId: string }, readonly "outbox.state-changed": { readonly intent: OutboxIntent }, readonly "room.job-stream": RoomJobStreamPayload, readonly "room.turn-stream": RoomTurnStreamPayload, readonly "stage.catalog-invalidated": { readonly reason: string }, readonly "query.invalidated": { readonly name: QueryName }, readonly "stage.registry-changed": { readonly appNames: readonly string[] }, readonly "sync.delta-applied": { readonly domain: string, readonly cursor: string }, readonly "transport.state-changed": { readonly state: TransportState } }} KernelEventPayloads */
+/** @template {KernelEventType} T @typedef {T extends CoreKernelEventType ? KernelEventPayloads[T] : AppEventPayload} KernelEventPayload */
+/** @template {KernelEventType} T @typedef {{ readonly occurredAt: string, readonly payload: KernelEventPayload<T>, readonly type: T }} KernelEventByType */
+/** @typedef {{ readonly occurredAt: string, readonly payload: AppEventPayload, readonly type: AppEventType }} AppDomainEvent */
+/** @typedef {{ [T in CoreKernelEventType]: KernelEventByType<T> }[CoreKernelEventType] | AppDomainEvent} DomainEvent */
+
+/** @template {CoreKernelEventType} T @param {DomainEvent} event @param {T} type @returns {event is Extract<DomainEvent, { readonly type: T }>} */
+export function isCoreKernelEvent(event, type) {
+  return event.type === type;
+}
+
+/** @param {string} value @returns {value is CoreKernelEventType} */
+export function isCoreKernelEventType(value) {
+  return KERNEL_EVENT_TYPES.includes(
+    /** @type {CoreKernelEventType} */ (value),
+  );
+}
+
+/** @param {string} value @returns {value is AppEventType} */
+export function isAppEventType(value) {
+  return parseAppEventType(value) !== undefined;
+}
+
+/** @param {string} value @returns {value is KernelEventType} */
+export function isKernelEventType(value) {
+  return isCoreKernelEventType(value) || isAppEventType(value);
+}
+
+/** @param {string} value @returns {string | undefined} */
+export function appEventResource(value) {
+  return parseAppEventType(value)?.resource;
+}
+
+/** @param {string} value @returns {string | undefined} */
+export function appEventInstance(value) {
+  return parseAppEventType(value)?.instance;
+}
+
+/** @param {string} value @returns {AppEventType | undefined} */
+export function appEventScope(value) {
+  const parsed = parseAppEventType(value);
+  return parsed === undefined ? undefined : `app.${parsed.resource}`;
+}
+
+/** @param {string} resource @param {string} [instance] @returns {AppEventType} */
+export function appEventType(resource, instance) {
+  if (!APP_EVENT_RESOURCE_PATTERN.test(resource)) {
+    throw new TypeError(`Invalid app event resource: ${resource}`);
+  }
+  if (instance === undefined) return `app.${resource}`;
+  if (!APP_EVENT_INSTANCE_PATTERN.test(instance)) {
+    throw new TypeError(`Invalid app event instance: ${instance}`);
+  }
+  return `app.${resource}#${instance}`;
+}
+
+/** @param {string} value @returns {value is QueryName} */
+export function isQueryName(value) {
+  return /^.+\.v\d+$/u.test(value);
+}