@usefidel/contracts 0.11.0 → 0.12.0

package/dist/analytics.d.ts

@@ -6,14 +6,29 @@
  * (webapp, landing).
  *
  * WHY THIS IS A PACKAGE AND NOT A LOCAL FILE PER SURFACE.
- * The webapp and the extension each identified the same human under a
- * different PostHog `distinct_id` — the webapp by Supabase UUID-or-email, the
- * extension by email-or-Figma-handle. `extension/src/lib/posthog.ts` carried a
- * comment asserting the two agreed. They did not. Nothing failed; retention
- * cohorts were simply wrong, and stayed wrong, because the two "authoritative"
- * definitions lived in two repositories with no gate between them.
- *
- * The package is the only mechanism that spans both repositories.
+ * The webapp and the extension each wrote their own identity rule, and the two
+ * rules were written to agree. In the common case they did: both normally
+ * identified a person by email.
+ *
+ * The defect was in what happened around that agreement.
+ *
+ *  1. EMAIL IS MUTABLE. A `distinct_id` must be stable for the life of the
+ *     person, and an email address is not — changing it forks one human into
+ *     two identities with no event connecting them.
+ *  2. THE FALLBACKS DIVERGED. Email is not always available, and each surface
+ *     fell back into a DIFFERENT namespace when it was missing — a Supabase
+ *     UUID on one side, a Figma handle on the other. So the same human was
+ *     identified consistently right up until the moment they were not, which
+ *     is the hardest version of this bug to see.
+ *  3. NOTHING GATED THE DUPLICATE. The rule was written out twice, in two
+ *     repositories, with no check that the two copies still said the same
+ *     thing. A drift would have been silent — and an earlier comment in
+ *     `extension/src/lib/posthog.ts` asserting the two agreed is exactly the
+ *     kind of claim a gate exists to replace.
+ *
+ * Nothing failed loudly. Retention cohorts were simply wrong, and stayed wrong.
+ * The package is the only mechanism that spans both repositories, so it is the
+ * only place the rule can be stated once.
  *
  * WHAT THIS OWNS: event NAMES and property TYPES.
  * WHAT IT DOES NOT OWN: SDK initialization, identity resolution, storage,
@@ -42,7 +57,21 @@ import { type RunErrorCode } from './run-errors.js';
  * history survives; the meaning of their events does not.
  */
 export declare const ANALYTICS_SCHEMA_VERSION: 2;
-/** Which client emitted the event. Server-side surfaces do not emit at all. */
+/**
+ * Which PRODUCT JOURNEY the event belongs to — not which process emitted it.
+ *
+ * This comment used to read "server-side surfaces do not emit at all", and that
+ * stopped being true when authoritative terminal events moved into the
+ * `web-validate` finalizer. A validation started from the web app is a webapp
+ * validation whether the browser or the backend reports its outcome, so the
+ * backend's `web_validation_completed` correctly carries `surface: 'webapp'`.
+ *
+ * Making the backend its own surface would split one funnel in half: the
+ * submission would sit under `webapp` and its completion under something else,
+ * and no tile could relate them without a union. Which process emitted an event
+ * is answered by the event NAME and by `release`, both of which already
+ * distinguish the two.
+ */
 export type AnalyticsSurface = 'landing' | 'webapp' | 'extension';
 /** Which deployment emitted the event. Drives the default dashboard filter. */
 export type AnalyticsEnvironment = 'production' | 'staging' | 'development';
@@ -130,13 +159,16 @@ export type GaEventName = (typeof GA_EVENT_NAMES)[number];
 export type SecondaryEventName = (typeof SECONDARY_EVENT_NAMES)[number];
 export type AnalyticsEventName = GaEventName | SecondaryEventName;
 /**
- * Stamped on every schema-2 event by the wrapper, not by call sites.
+ * Stamped on every schema-2 event by the emitter, not by call sites — the
+ * browser wrapper for client events, `_shared/analytics.ts` for the backend
+ * terminal events.
  *
- * `team_id` and `is_internal` are optional because the extension cannot get
- * them without a network request it is not allowed to make: `team_id` lives in
- * `profiles`, not in the Supabase JWT. Team-level analysis uses
+ * `fidel_team_id` and `is_internal` are optional because the extension cannot
+ * get them without a network request it is not allowed to make: the team lives
+ * in `profiles`, not in the Supabase JWT. Team-level analysis uses
  * `validation_runs.team_id` in the database instead. The webapp has both and
- * always sends them.
+ * always sends them, and the backend reads both from the resolved team
+ * context it already loaded to run the subscription gate.
  *
  * There is no `user_id` field. The Supabase UUID is the `distinct_id`;
  * duplicating it as a property invites two sources of truth for identity.
@@ -147,7 +179,23 @@ export interface AnalyticsContext {
     surface: AnalyticsSurface;
     /** Git SHA (webapp/landing) or `manifest.json` version (extension). */
     release: string;
-    team_id?: string;
+    /**
+     * The Fidel team, PREFIXED — and the prefix is not cosmetic.
+     *
+     * `team_id` is a reserved top-level column on PostHog's own events table (it
+     * holds the PostHog project id). A property of that name is still stored in
+     * the payload, but `properties.team_id` resolves to the reserved column and
+     * returns NULL, so every dashboard filter and breakdown built on it silently
+     * matches nothing. Measured on staging 2026-09-08:
+     *
+     *   JSONExtractString(properties,'team_id') -> b34bb03c-…   (the real value)
+     *   properties.team_id                      -> NULL
+     *   team_id                                 -> 330851       (PostHog's project)
+     *
+     * That is the worst failure shape available: instrumented, ingested, and
+     * invisible. `is_internal` does not collide and keeps its plain name.
+     */
+    fidel_team_id?: string;
     is_internal?: boolean;
 }
 /**

package/dist/analytics.js

@@ -6,14 +6,29 @@
  * (webapp, landing).
  *
  * WHY THIS IS A PACKAGE AND NOT A LOCAL FILE PER SURFACE.
- * The webapp and the extension each identified the same human under a
- * different PostHog `distinct_id` — the webapp by Supabase UUID-or-email, the
- * extension by email-or-Figma-handle. `extension/src/lib/posthog.ts` carried a
- * comment asserting the two agreed. They did not. Nothing failed; retention
- * cohorts were simply wrong, and stayed wrong, because the two "authoritative"
- * definitions lived in two repositories with no gate between them.
+ * The webapp and the extension each wrote their own identity rule, and the two
+ * rules were written to agree. In the common case they did: both normally
+ * identified a person by email.
  *
- * The package is the only mechanism that spans both repositories.
+ * The defect was in what happened around that agreement.
+ *
+ *  1. EMAIL IS MUTABLE. A `distinct_id` must be stable for the life of the
+ *     person, and an email address is not — changing it forks one human into
+ *     two identities with no event connecting them.
+ *  2. THE FALLBACKS DIVERGED. Email is not always available, and each surface
+ *     fell back into a DIFFERENT namespace when it was missing — a Supabase
+ *     UUID on one side, a Figma handle on the other. So the same human was
+ *     identified consistently right up until the moment they were not, which
+ *     is the hardest version of this bug to see.
+ *  3. NOTHING GATED THE DUPLICATE. The rule was written out twice, in two
+ *     repositories, with no check that the two copies still said the same
+ *     thing. A drift would have been silent — and an earlier comment in
+ *     `extension/src/lib/posthog.ts` asserting the two agreed is exactly the
+ *     kind of claim a gate exists to replace.
+ *
+ * Nothing failed loudly. Retention cohorts were simply wrong, and stayed wrong.
+ * The package is the only mechanism that spans both repositories, so it is the
+ * only place the rule can be stated once.
  *
  * WHAT THIS OWNS: event NAMES and property TYPES.
  * WHAT IT DOES NOT OWN: SDK initialization, identity resolution, storage,

package/package.json

@@ -7,7 +7,7 @@
     "The source of truth still lives in the monorepo at packages/contracts/."
   ],
   "name": "@usefidel/contracts",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Shared, code-free contracts between Fidel surfaces. Run-error taxonomy, theme-intake wire types, and the canonical fidel.config.json builders.",
   "license": "UNLICENSED",
   "private": false,