@hyodotdev/openiap-commerce-protocol 0.0.0-bootstrap.0 → 0.1.0

package/package.json

@@ -1,21 +1,71 @@
 {
   "name": "@hyodotdev/openiap-commerce-protocol",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Namespace registration for Vendor-neutral server-side commerce contract",
-  "license": "MIT",
+  "version": "0.1.0",
+  "type": "module",
+  "types": "./src/index.d.ts",
+  "main": "./src/index.mjs",
+  "description": "OpenIAP Commerce Protocol: a vendor-neutral server-side contract for purchase verification, entitlements, lifecycle events, and REST and GraphQL bindings",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    },
+    "./commerce-protocol.graphql": "./generated/commerce-protocol.graphql",
+    "./generated/schemas/*": "./generated/schemas/*",
+    "./generated/vectors/*": "./generated/vectors/*",
+    "./examples/*": "./examples/*",
+    "./vectors/*": "./vectors/*",
+    "./generated/bindings/*": "./generated/bindings/*",
+    "./generated/openapi/*": "./generated/openapi/*",
+    "./conformance": {
+      "types": "./conformance/index.d.ts",
+      "default": "./conformance/index.mjs"
+    },
+    "./schema/*": "./schema/*"
+  },
+  "scripts": {
+    "build": "node scripts/assemble-schema.mjs && node scripts/build-json-schemas.mjs && node scripts/build-bundle.mjs && node scripts/build-lifecycle-vectors.mjs && node scripts/build-operations.mjs",
+    "test": "node scripts/assemble-schema.mjs --check && node scripts/build-json-schemas.mjs --check && node scripts/build-bundle.mjs --check && node scripts/build-lifecycle-vectors.mjs --check && node scripts/build-operations.mjs --check && prettier --check \"**/*.{graphql,json,md,mjs,ts}\" && vitest run test && node scripts/quickstart.mjs",
+    "quickstart": "node scripts/quickstart.mjs"
+  },
+  "keywords": [
+    "openiap",
+    "iap",
+    "in-app-purchase",
+    "commerce",
+    "webhook",
+    "specification"
+  ],
   "author": "hyodotdev",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "graphql": "^16.11.0",
+    "prettier": "^3.6.2",
+    "vitest": "^4.1.11"
+  },
+  "packageManager": "bun@1.3.13",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "CONVENTION.md",
+    "SPEC.md",
+    "DESIGN.md",
+    "schema",
+    "generated",
+    "examples",
+    "vectors",
+    "src",
+    "conformance"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/hyodotdev/openiap.git",
     "directory": "specs/commerce-protocol"
   },
-  "homepage": "https://openiap.dev",
-  "files": [
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
+  "homepage": "https://openiap.dev/commerce-protocol"
 }

package/schema/01-primitives.graphql

@@ -0,0 +1,102 @@
+# The OpenIAP Commerce Protocol contract, in the GraphQL SDL dialect the
+# compiler in scripts/ understands. This directory is the authored source:
+# each file is one logical layer, assembled in filename order into the
+# published single-file contract commerce-protocol.graphql.
+#
+# This is not a served API. The custom directives retain the JSON wire
+# constraints that standard GraphQL cannot express, and each Query/Mutation
+# field's @operation directive carries its transport binding. The compiler
+# emits the JSON Schemas used by validators, the HTTP binding manifest, the
+# executable GraphQL projection, the OpenAPI document, and the operation
+# conformance vectors.
+#
+# Wire presence is explicit: T! is required and non-null, T is required and
+# nullable, and @optional permits omission without changing nullability.
+# Operation input and result types never combine nullable with @optional:
+# the GraphQL binding cannot express omitted-vs-null, so an omitted member
+# and a selected-but-null member must mean the same thing there.
+
+# Published primitives -------------------------------------------------------
+
+"""
+The commerce platform that is authoritative for the purchase. This is a store, not a device platform: one device platform can host several stores. The value space is OPEN. The listed values are the stores this version names, but an implementation that observes commerce on another platform MUST be able to emit it, and a consumer MUST accept and preserve an unrecognised store opaquely rather than reject the event. Use a lowercase, stable, unambiguous token.
+"""
+scalar Store
+  @definition(schema: "primitives")
+  @jsonString(
+    pattern: "^[a-z][a-z0-9_]*$"
+    examples: ["apple", "google", "horizon", "amazon"]
+  )
+
+"""
+The store environment the purchase belongs to. The value space is open: receivers MUST accept and preserve an unrecognised value opaquely and MUST NOT reject an event because of it.
+"""
+scalar Environment
+  @definition(schema: "primitives")
+  @jsonString(minLength: 1, examples: ["production", "sandbox", "xcode"])
+
+"""
+An instant, as integer milliseconds since the Unix epoch, UTC. Every timestamp in this specification uses this encoding. The one exception is the transport signature timestamp, which is in seconds; see the webhook section of SPEC.md.
+"""
+scalar Timestamp @definition(schema: "primitives") @jsonInteger(minimum: 0)
+
+"""
+An opaque, implementation-assigned identifier. Consumers MUST treat it as an opaque string and MUST NOT parse structure out of it.
+"""
+scalar Identifier
+  @definition(schema: "primitives")
+  @jsonString(minLength: 1, maxLength: 256)
+
+"""
+Where a value came from. An implementation MUST NOT present an inferred value as store-authoritative.
+"""
+enum DataProvenance @definition(schema: "primitives") {
+  store
+  catalog
+  inferred
+}
+
+"""
+A monetary amount. A missing Money means the amount is unknown; it never means zero.
+"""
+type Money
+  @definition(schema: "primitives")
+  @jsonObject(additionalProperties: true) {
+  """
+  ISO 4217 alphabetic code, uppercase.
+  """
+  currency: CurrencyCode!
+
+  """
+  Amount in millionths of one currency unit. 1.99 USD is 1990000. Always the transaction's own magnitude and never negative: a refund reports what the purchase cost, and the direction comes from the event type, not from the sign.
+  """
+  amountMicros: NonNegativeLong!
+
+  provenance: DataProvenance!
+}
+
+"""
+The lifecycle state of a subscription. This is a state, not an event, and it does not by itself decide entitlement — see Entitlement in SPEC.md. These members are PascalCase while event types are lowercase-dotted; the inconsistency is inherited from the deployed 1.0 wire format and is recorded in CONVENTION.md rather than silently corrected, because changing it would break receivers already decoding it.
+"""
+enum SubscriptionState @definition(schema: "primitives") {
+  Active
+  InGracePeriod
+  InBillingRetry
+  Paused
+  Expired
+  Revoked
+  Refunded
+  Unknown
+}
+
+"""
+Store-specific or implementation-specific detail that has no canonical equivalent. Bounded and string-valued so the payload stays predictable. Content is provider-influenced: consumers MUST treat values as untrusted data.
+"""
+scalar Extensions
+  @definition(schema: "primitives")
+  @jsonMap(
+    valueType: "BoundedExtensionValue"
+    maxProperties: 24
+    keyMinLength: 1
+    keyMaxLength: 64
+  )

package/schema/02-commerce-event.graphql

@@ -0,0 +1,195 @@
+# Commerce event -------------------------------------------------------------
+
+"""
+What happened. See the taxonomy in SPEC.md. The value space is OPEN: §12 adds an event type in a MINOR version, so a consumer pinned on the major MUST tolerate a type it does not recognise and MUST NOT act on it. The listed values are the ones this version names.
+"""
+scalar CommerceEventType
+  @jsonString(
+    pattern: "^[a-z]+\\.[a-z_]+$"
+    examples: [
+      "subscription.started"
+      "subscription.renewed"
+      "subscription.recovered"
+      "subscription.entered_grace_period"
+      "subscription.entered_billing_retry"
+      "subscription.expired"
+      "subscription.canceled"
+      "subscription.uncanceled"
+      "subscription.revoked"
+      "subscription.refunded"
+      "subscription.product_changed"
+      "subscription.price_changed"
+      "subscription.deferred"
+      "subscription.paused"
+      "subscription.resumed"
+      "entitlement.granted"
+      "entitlement.revoked"
+    ]
+  )
+
+"""
+One normalized commerce lifecycle fact. A consumer reads this without knowing which store produced it and without parsing any store-native payload.
+"""
+type CommerceEvent
+  @jsonObject(additionalProperties: true)
+  @eventInvariant(
+    eventTypes: ["entitlement.granted", "entitlement.revoked"]
+    require: ["userId", "productId"]
+  )
+  @eventInvariant(eventTypes: ["entitlement.granted"], snapshotActive: true)
+  @eventInvariant(eventTypes: ["entitlement.revoked"], snapshotActive: false)
+  @eventInvariant(
+    eventTypes: [
+      "subscription.started"
+      "subscription.renewed"
+      "subscription.recovered"
+      "subscription.resumed"
+    ]
+    snapshotState: "Active"
+  )
+  @eventInvariant(
+    eventTypes: ["subscription.entered_grace_period"]
+    snapshotState: "InGracePeriod"
+  )
+  @eventInvariant(
+    eventTypes: ["subscription.entered_billing_retry"]
+    snapshotState: "InBillingRetry"
+    snapshotActive: false
+  )
+  @eventInvariant(
+    eventTypes: ["subscription.expired"]
+    snapshotState: "Expired"
+    snapshotActive: false
+  )
+  @eventInvariant(
+    eventTypes: ["subscription.revoked"]
+    snapshotState: "Revoked"
+    snapshotActive: false
+  )
+  @eventInvariant(
+    eventTypes: ["subscription.refunded"]
+    snapshotState: "Refunded"
+    snapshotActive: false
+  )
+  @eventInvariant(
+    eventTypes: ["subscription.paused"]
+    snapshotState: "Paused"
+    snapshotActive: false
+  ) {
+  """
+  Unique identity of this event, assigned by the emitter. It is the receiver's deduplication key. An emitter MUST NOT reuse an eventId and MUST NOT change the eventId of an event it has already delivered.
+  """
+  eventId: Identifier!
+
+  """
+  What happened. See the taxonomy in SPEC.md. The value space is OPEN: §12 adds an event type in a MINOR version, so a consumer pinned on the major MUST tolerate a type it does not recognise and MUST NOT act on it. The listed values are the ones this version names.
+  """
+  eventType: CommerceEventType!
+
+  """
+  Schema version of this body, as MAJOR.MINOR. Consumers pin on the major.
+  """
+  eventVersion: MajorMinor!
+
+  """
+  The best authoritative time for the commerce fact. Use the store-asserted transition time when one exists. When polling only reveals that a value changed since the last observation, use the time the emitter observed the new value and do not invent a more precise instant.
+  """
+  occurredAt: Timestamp!
+
+  """
+  When the emitter derived this event. Always greater than or equal to occurredAt in practice, but not guaranteed by this specification.
+  """
+  processedAt: Timestamp!
+
+  store: Store!
+  environment: Environment!
+
+  """
+  The emitter-side scope this event belongs to, opaque to the consumer. A scope is whatever boundary the emitter organises commerce by — a tenant, a project, an application, or a single constant when the emitter serves exactly one. It is NOT an identifier issued by any central registry, and an implementation MUST NOT be required to obtain one from a third party. The member name is inherited from the deployed 1.0 wire format.
+  """
+  projectId: Identifier!
+
+  """
+  A finer-grained scope within `projectId`, when the emitter models one. Opaque to the consumer.
+  """
+  applicationId: Identifier! @optional
+
+  """
+  The app user this purchase is bound to, expressed in the identity space shared by the emitter and its consumer. It is an opaque correlation handle: there is no global user directory, and no central identity resolution is implied or required. Absent when no binding exists; required on every entitlement event.
+  """
+  userId: Identifier! @optional
+
+  """
+  Store product identifier this event concerns. Required on every entitlement event so a consumer knows which access decision to apply.
+  """
+  productId: NonEmptyString! @optional
+
+  """
+  The product that was canonical before this event, when the event applies a product switch.
+  """
+  previousProductId: NonEmptyString! @optional
+
+  """
+  Store transaction identity for this specific economic event, where the store exposes one.
+  """
+  transactionId: NonEmptyString! @optional
+
+  """
+  Store identity of the first transaction in this subscription chain, where the store exposes one.
+  """
+  originalTransactionId: NonEmptyString! @optional
+
+  """
+  The subscription as it stood immediately after this event. Absent for stores that keep no canonical subscription record.
+  """
+  subscription: SubscriptionSnapshot! @optional
+
+  """
+  Amount associated with the transaction this event concerns, carried at whatever provenance it has — only `store` means the store asserted it. Always the transaction's own magnitude and never negative. It is context rather than a charge record: stores repeat the same figure across successive notifications about one subscription, so a consumer MUST NOT sum every priced event. See SPEC.md 9.3. Absent means the amount is unknown, never zero.
+  """
+  price: Money! @optional
+
+  """
+  The store's own notification identifier this event was derived from, for support triage against the store console. Absent when the event did not originate from a store notification.
+  """
+  sourceStoreEventId: NonEmptyString! @optional
+
+  extensions: Extensions! @optional
+}
+
+"""
+The subscription as it stood immediately after this event. Absent for stores that keep no canonical subscription record.
+"""
+type SubscriptionSnapshot @inline @jsonObject(additionalProperties: true) {
+  state: SubscriptionState!
+
+  """
+  The product the subscription is on after this event. Not always the event's top-level `productId`: where a store defers a product change to the next period — Apple's scheduled downgrades do, Google's item changes do not — the top level names the incoming product while this stays on the outgoing one until it renews. A consumer gating access reads this member; one reporting on what the notification announced reads the top level.
+  """
+  productId: NonEmptyString!
+
+  """
+  When access ends. This is the boundary the entitlement predicate compares against, and the comparison is exclusive — at this instant the subscription is no longer entitled. During a grace period it is the end of the grace window, not of the period that failed to renew; an emitter that reports the failed period here revokes access at the moment grace begins.
+  """
+  expiresAt: Timestamp! @optional
+
+  """
+  When the store will next attempt to bill, when it reports one. Distinct from `expiresAt`, which is when access ends: they coincide on a healthy subscription and diverge while a grace period extends access past the billing date. Absent once renewal is no longer expected.
+  """
+  renewsAt: Timestamp! @optional
+
+  """
+  Whether the store will attempt another billing period. False after a cancellation, while access may still be live.
+  """
+  willRenew: Boolean! @optional
+
+  """
+  Why the subscription stopped renewing, as a normalized token — not the store's own wording, which the emitter translates from whatever shape that store uses. This version names `UserCanceled`, `BillingError`, `PriceIncreaseDeclined`, `ProductUnavailable`, `Refunded` and `Other`; the space is open, so a consumer MUST tolerate a token it does not know, and no store yields every token. An emitter that has no store-asserted reason omits this member. Unlike `price`, it has no provenance marker, so treat a present value as advisory rather than as a fact to bill or report on.
+  """
+  cancellationReason: NonEmptyString! @optional
+
+  """
+  The entitlement gate after this event. Where this member is present it is the field to read for access — never a re-derivation from `state`. A store that keeps no canonical subscription record omits the whole `subscription` member; there an `entitlement.granted` or `entitlement.revoked` event carries the decision in its type, while a `subscription.*` event carries none.
+  """
+  active: Boolean!
+}

package/schema/03-provider-capabilities.graphql

@@ -0,0 +1,139 @@
+# Provider capabilities ------------------------------------------------------
+
+scalar StoreCapabilitiesMap
+  @jsonMap(
+    valueType: "StoreCapabilities"
+    minProperties: 1
+    keyPattern: "^[a-z][a-z0-9_]*$"
+  )
+
+"""
+What an implementation supports: the specification version it speaks, the event types it can emit, and what it can actually observe per store. This is the document a consumer, an operator, or a tool reads to determine compatibility without guessing and without reading prose. It contains no commerce data.
+"""
+type ProviderCapabilities @jsonObject(additionalProperties: true) {
+  """
+  OpenIAP Commerce Protocol version this declaration was written against, as MAJOR.MINOR.
+  """
+  specVersion: MajorMinor!
+
+  """
+  Free-form name and version of the backend making this declaration. Present so an operator can tell two backends apart; it carries no normative meaning.
+  """
+  implementation: Implementation! @optional
+
+  """
+  Event types this implementation can emit. A consumer uses it to know which lifecycle signals to expect; absence of a type here means this implementation never produces it, which is different from a type that simply has not occurred yet.
+  """
+  eventTypes: [NamespacedEventType!]! @jsonArray(minItems: 1, uniqueItems: true)
+
+  """
+  Keyed by store, using the same open value space as the event envelope. An implementation declares only the stores it actually integrates.
+  """
+  stores: StoreCapabilitiesMap!
+
+  """
+  Operation profiles this implementation serves, keyed by profile name with the profile version as the value. This version names `verification`, `entitlements`, `events`, and `accountLifecycle`; the key space is open, so a consumer MUST ignore a profile it does not recognise. An implementation MUST declare only profiles it implements and passes conformance for, and MUST NOT declare a profile it partially implements. Absent on a descriptor from an events-only emitter that predates the operation surface.
+  """
+  profiles: ProfileVersionMap! @optional
+
+  """
+  Transport bindings this implementation serves for the declared profiles, keyed by binding name with the binding version as the value. This version names `rest` and `graphql`; the key space is open. Declaring a binding means every declared profile operation is reachable over it. An implementation MAY serve one binding only. Absent on a descriptor from an events-only emitter.
+  """
+  bindings: BindingVersionMap! @optional
+}
+
+scalar ProfileVersionMap
+  @jsonMap(
+    valueType: "MajorMinor"
+    minProperties: 1
+    keyPattern: "^[a-z][a-zA-Z0-9]*$"
+  )
+
+scalar BindingVersionMap
+  @jsonMap(
+    valueType: "MajorMinor"
+    minProperties: 1
+    keyPattern: "^[a-z][a-zA-Z0-9]*$"
+  )
+
+"""
+Free-form name and version of the backend making this declaration. Present so an operator can tell two backends apart; it carries no normative meaning.
+"""
+type Implementation @inline @jsonObject(additionalProperties: true) {
+  """
+  Name of the backend making this declaration, for an operator reading a descriptor without knowing where it came from.
+  """
+  name: NonEmptyString! @optional
+
+  """
+  Version of that backend, when it publishes one. Not a specification version — that is `specVersion`.
+  """
+  version: NonEmptyString! @optional
+}
+
+"""
+What one store's commerce surface offers and what this backend consumes of it, axis by axis. The container stays open: a version that names a new axis is a MINOR addition older consumers ignore.
+"""
+type StoreCapabilities
+  @definition(schema: "provider-capabilities")
+  @jsonObject(additionalProperties: true) {
+  """
+  Server-side receipt or token validation on demand.
+  """
+  initialValidation: Support!
+  """
+  The store pushes lifecycle notifications to the backend.
+  """
+  serverNotifications: Support!
+  """
+  A canonical subscription record can be maintained for this store.
+  """
+  subscriptions: Support!
+  """
+  Renewal is observable as a distinct lifecycle event.
+  """
+  renewalEvents: Support!
+  """
+  Refund or revocation is observable as a distinct lifecycle event.
+  """
+  refundEvents: Support!
+  """
+  Expiration is observable, rather than only inferred from a timestamp having passed.
+  """
+  expiration: Support!
+  """
+  A scheduled pass re-reads authoritative store state, so a lost notification can self-heal.
+  """
+  reconciliation: Support!
+  """
+  Entitlement is derivable for access gating.
+  """
+  entitlements: Support!
+  """
+  The store asserts an amount that can be attributed to revenue with `store` provenance.
+  """
+  revenueAmount: Support!
+}
+
+"""
+Two axes, deliberately separate. `provider` is what the store's own API offers; `implementation` is what this backend actually consumes. They differ in practice — a store can publish a notification channel that a given backend has not integrated — and collapsing them into one boolean produces a dishonest matrix.
+"""
+type Support
+  @definition(schema: "provider-capabilities")
+  @jsonObject(additionalProperties: false)
+  @supportInvariant {
+  """
+  Whether the store's own API offers this at all. A fact about the store, independent of any backend.
+  """
+  provider: Boolean!
+
+  """
+  Whether this backend consumes it. False against a true `provider` is an implementation gap, not a store limitation.
+  """
+  implementation: Boolean!
+
+  """
+  Required whenever `provider` and `implementation` disagree, or whenever either is false. States the concrete limitation in prose a support engineer can act on.
+  """
+  notes: NonEmptyString! @optional
+}

package/schema/04-store-event-mapping.graphql

@@ -0,0 +1,98 @@
+# Store event mapping --------------------------------------------------------
+
+scalar StoreMappingMap
+  @jsonMap(
+    valueType: "StoreMapping"
+    minProperties: 1
+    keyPattern: "^[a-z][a-z0-9_]*$"
+  )
+
+"""
+How each store's own notification vocabulary maps onto the normalized event types. This is the reference an implementer follows to normalize a store notification without reverse-engineering an existing backend, and the reference a consumer reads to understand why a given store produces the events it does. A row states what a notification means, not that an emitter can always act on it: one that lacks the state to interpret a notification — a redelivery it already applied, a purchase whose product it cannot resolve, a token the store has superseded — emits nothing, and that is conformant.
+"""
+type StoreEventMapping @jsonObject(additionalProperties: true) {
+  """
+  OpenIAP Commerce Protocol version this table was written against, as MAJOR.MINOR.
+  """
+  specVersion: MajorMinor!
+
+  """
+  Keyed by store, using the same open value space as the event envelope. A table lists only the stores it has mappings for.
+  """
+  stores: StoreMappingMap!
+}
+
+"""
+One store's notification lane: the channel it publishes, the rows that translate its notifications, and what an emitter could still derive without one.
+"""
+type StoreMapping
+  @definition(schema: "store-event-mapping")
+  @jsonObject(additionalProperties: true)
+  @storeMappingInvariant {
+  """
+  The store's own server-to-server notification product, or null when the store publishes none. This is a fact about the STORE, never about any implementation: a channel a store publishes but this version does not map is still named here, with `mappings` empty and `notes` saying why. Recording an unmapped channel as null would collapse a store limitation and a specification gap into the same value, which is the conflation the capability descriptor's two axes exist to prevent.
+  """
+  notificationChannel: String
+
+  """
+  Required when there is no notification channel, or when the store's semantics need a caveat an implementer would otherwise get wrong.
+  """
+  notes: NonEmptyString! @optional
+
+  """
+  Events an implementation could produce for this store by re-asking an authoritative endpoint on a schedule rather than by consuming a notification. Present so that a store this version maps no notifications for is not mistaken for a store with no possible signal — which is true whether the store publishes a channel that went unmapped or publishes none at all. This version specifies no cadence, so an implementation that derives these MUST still declare its capabilities honestly rather than claim parity with a store whose notifications it consumes.
+  """
+  derivableByPolling: [EntitlementEventType!]!
+    @optional
+    @jsonArray(uniqueItems: true)
+
+  """
+  Notification-to-event rows. Empty when the store publishes no channel, or when it publishes one this version does not map; `notes` MUST distinguish the two.
+  """
+  mappings: [Mapping!]!
+}
+
+"""
+One notification-to-event row. Closed: an unrecognised qualifier would leave a reader selecting this row on fewer conditions than its author intended.
+"""
+type Mapping
+  @definition(schema: "store-event-mapping")
+  @jsonObject(additionalProperties: false)
+  @mappingInvariant {
+  """
+  The notification type in the store's own vocabulary, verbatim.
+  """
+  storeNotification: NonEmptyString!
+
+  """
+  The value the store actually transmits, when it differs from the human-readable name. Google Play sends a numeric notificationType; the names are documentation labels that never appear on the wire.
+  """
+  storeNotificationCode: NonEmptyString! @optional
+
+  """
+  A qualifier the store sends alongside the type. Null means this row is the default for that notification: it applies when the store sends no subtype, and also when it sends one no other row claims.
+  """
+  storeSubtype: String @optional
+
+  """
+  Restricts this row to the case where the emitter has seen no earlier store notification for this purchase. That covers both a purchase it has never heard of and one it learned about from a client receipt but never from the store — in each case the notification is the beginning of the story it can tell. A purchase with store history behind it takes the unconditional row instead.
+  """
+  whenNoPriorStoreEvent: Boolean! @optional @jsonConst(boolean: true)
+
+  """
+  Restricts this row to the case where the subscription was in one of these states immediately before the notification. Use it only where the store itself provides no qualifier: Google sends SUBSCRIPTION_RECOVERED for both a recovery and a resume from pause and marks nothing, so prior state is the only separator. Where a store does send a qualifier, use `storeSubtype` instead. A row without any condition is the default for its (notification, subtype) pair, and an implementation MUST prefer a conditional row that matches.
+  """
+  whenPreviousState: [SubscriptionState!]!
+    @optional
+    @jsonArray(minItems: 1, uniqueItems: true)
+
+  """
+  The normalized event type to emit, or null when the notification is received but produces no event — an audit-only or informational notification. A null event is a deliberate mapping, not a gap. Never an `entitlement.*` type: SPEC.md 9.2 derives those from the gate, not from a notification.
+  """
+  event: SubscriptionEventType
+
+  """
+  Why this row is what it is, in prose an implementer can act on. Required wherever the row emits nothing, so a reader can tell a deliberate no-op from an oversight.
+  """
+  notes: NonEmptyString! @optional
+}