@usefidel/contracts 0.10.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 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,
@@ -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';
@@ -112,7 +141,7 @@ export declare function errorPhaseFor(code: string | null | undefined): Validati
 /** True when `code` is a member of the current taxonomy. */
 export declare function isKnownErrorCode(code: string | null | undefined): code is RunErrorCode;
 /** Events the GA dashboard is built on. Typed properties, specified triggers. */
-export declare const GA_EVENT_NAMES: readonly ["signup_started", "signup_completed", "onboarding_started", "onboarding_completed", "figma_connected", "environment_connected", "web_validation_submitted", "web_validation_completed", "web_validation_failed", "web_validation_cancelled", "report_viewed", "report_share_created", "report_link_copied", "report_share_failed", "report_copy_failed", "diff_mark_resolved", "upgrade_clicked", "checkout_started", "feedback_submitted", "extension_opened", "validation_start", "validation_accepted", "validation_complete", "validation_error", "validation_cancel", "review_saved", "figma_auth_success", "figma_auth_error", "extension_share_copied", "upgrade_modal_viewed", "upgrade_cta_clicked"];
+export declare const GA_EVENT_NAMES: readonly ["signup_started", "signup_completed", "onboarding_started", "onboarding_completed", "figma_connected", "environment_connected", "web_validation_submitted", "web_validation_completed", "web_validation_failed", "validation_cancel_requested", "validation_result_observed", "report_viewed", "report_share_created", "report_link_copied", "report_share_failed", "report_copy_failed", "diff_mark_resolved", "upgrade_clicked", "checkout_started", "feedback_submitted", "extension_opened", "validation_start", "validation_accepted", "validation_complete", "validation_error", "validation_cancel", "review_saved", "figma_auth_success", "figma_auth_error", "extension_share_copied", "upgrade_modal_viewed", "upgrade_cta_clicked"];
 /**
  * Events that exist but are NOT GA metrics.
  *
@@ -125,18 +154,21 @@ export declare const GA_EVENT_NAMES: readonly ["signup_started", "signup_complet
  */
 export declare const SECONDARY_EVENT_NAMES: readonly ["checkout_completed", "console_errors", "diff_expanded", "drawer_filter_changed", "review_save_error", "review_verdict", "review_verdict_all", "screenshot_exported", "ui_crash", "validation_resume", "validation_retry", "view_changed", "auth_refresh", "consensus_complete", "consensus_error", "extension_validation_failed", "idempotency_dedup_client", "pipeline_complete", "pipeline_phase", "pipeline_resume", "rate_limit_hit", "upgrade_wall_hit"];
 /** Every event name any Fidel client may emit. */
-export declare const ANALYTICS_EVENT_NAMES: readonly ["signup_started", "signup_completed", "onboarding_started", "onboarding_completed", "figma_connected", "environment_connected", "web_validation_submitted", "web_validation_completed", "web_validation_failed", "web_validation_cancelled", "report_viewed", "report_share_created", "report_link_copied", "report_share_failed", "report_copy_failed", "diff_mark_resolved", "upgrade_clicked", "checkout_started", "feedback_submitted", "extension_opened", "validation_start", "validation_accepted", "validation_complete", "validation_error", "validation_cancel", "review_saved", "figma_auth_success", "figma_auth_error", "extension_share_copied", "upgrade_modal_viewed", "upgrade_cta_clicked", "checkout_completed", "console_errors", "diff_expanded", "drawer_filter_changed", "review_save_error", "review_verdict", "review_verdict_all", "screenshot_exported", "ui_crash", "validation_resume", "validation_retry", "view_changed", "auth_refresh", "consensus_complete", "consensus_error", "extension_validation_failed", "idempotency_dedup_client", "pipeline_complete", "pipeline_phase", "pipeline_resume", "rate_limit_hit", "upgrade_wall_hit"];
+export declare const ANALYTICS_EVENT_NAMES: readonly ["signup_started", "signup_completed", "onboarding_started", "onboarding_completed", "figma_connected", "environment_connected", "web_validation_submitted", "web_validation_completed", "web_validation_failed", "validation_cancel_requested", "validation_result_observed", "report_viewed", "report_share_created", "report_link_copied", "report_share_failed", "report_copy_failed", "diff_mark_resolved", "upgrade_clicked", "checkout_started", "feedback_submitted", "extension_opened", "validation_start", "validation_accepted", "validation_complete", "validation_error", "validation_cancel", "review_saved", "figma_auth_success", "figma_auth_error", "extension_share_copied", "upgrade_modal_viewed", "upgrade_cta_clicked", "checkout_completed", "console_errors", "diff_expanded", "drawer_filter_changed", "review_save_error", "review_verdict", "review_verdict_all", "screenshot_exported", "ui_crash", "validation_resume", "validation_retry", "view_changed", "auth_refresh", "consensus_complete", "consensus_error", "extension_validation_failed", "idempotency_dedup_client", "pipeline_complete", "pipeline_phase", "pipeline_resume", "rate_limit_hit", "upgrade_wall_hit"];
 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;
 }
 /**
@@ -179,7 +227,11 @@ export interface ValidationEventProperties {
  * upgrade wall still counted as started and no event could carry a `run_id`.
  * This one cannot be emitted without one.
  *
- * NOT a terminal event: exactly one of completed / failed / cancelled follows.
+ * NOT a terminal event. Emitted by the BROWSER, because acceptance is the
+ * browser's own observation: it made the request and read the response.
+ *
+ * Its terminal counterpart is emitted by the SERVER — see
+ * `WebValidationCompletedProperties` for why ownership splits here.
  */
 export interface ValidationSubmittedProperties extends ValidationEventProperties {
     /**
@@ -215,6 +267,30 @@ export interface ReportShareFailureProperties {
      */
     error_code: string;
 }
+/**
+ * An accepted run reached a terminal status. EMITTED BY THE BACKEND FINALIZER,
+ * immediately after the `validation_runs` status update succeeds.
+ *
+ * A browser cannot own this event. Validation is asynchronous: the edge
+ * function answers 202 and finishes the run in a background task, so the
+ * transition happens in a process the tab has no part in. A browser-emitted
+ * completion is really "the user was still watching when it landed", and a
+ * completion rate built on it has that as its hidden denominator. Measured on
+ * staging: three accepted runs, three `web_validation_submitted`, zero
+ * completions — including one on the fixed client, because the tab moved on
+ * before the run finished.
+ *
+ * The emit is strictly ordered after the status write and is skipped when that
+ * write fails, so this event cannot claim a completion the database does not
+ * have. Analytics failure never changes the validation result: a failed capture
+ * is logged and dropped.
+ *
+ * The server uses the SAME Supabase user UUID as `distinct_id` that the browser
+ * uses. Anything else forks the person.
+ *
+ * DEDUPLICATE BY DISTINCT `run_id`. Never count raw event rows: a retry inside
+ * the finalizer, or a replayed background task, can emit twice for one run.
+ */
 export interface WebValidationCompletedProperties extends ValidationEventProperties {
     duration_ms: number;
     /**
@@ -237,7 +313,17 @@ export interface WebValidationCompletedProperties extends ValidationEventPropert
     result_completeness?: ResultCompleteness;
 }
 /**
- * A run that failed or was cancelled.
+ * A validation failed.
+ *
+ * OWNERSHIP SPLITS ON `run_id`, and the nullability is what carries it:
+ *   - `run_id === null` — rejected BEFORE the backend accepted it (upgrade
+ *     wall, rate limit, invalid URL). Only the browser saw this; there is no
+ *     run and no server process to emit from. Browser-emitted.
+ *   - `run_id !== null` — an accepted run reached `status = 'error'`.
+ *     Backend-emitted, immediately after that status write succeeds, for the
+ *     same reason `web_validation_completed` is.
+ *
+ * DEDUPLICATE BY DISTINCT `run_id` for the accepted half.
  *
  * `run_id` is NULLABLE here and required on the success events, and the
  * asymmetry is the point: a run rejected BEFORE the backend accepted it — the
@@ -254,12 +340,51 @@ export interface ValidationFailedProperties {
     error_phase: ValidationErrorPhase;
     retryable: boolean;
 }
-export interface ValidationCancelledProperties {
+/**
+ * The user asked to stop, and the browser aborted its in-flight request.
+ *
+ * This is a REQUEST, not an outcome, and the name says so. `validation_runs`
+ * has no `cancelled` status — its check constraint allows only `complete`,
+ * `error`, `partial` and `processing` — so no accepted run can ever persist as
+ * cancelled. Aborting the client fetch does not stop the backend: the edge
+ * function answers 202 and finishes the run in a background task, so a run the
+ * user "cancelled" usually goes on to complete and emits
+ * `web_validation_completed` from the server a moment later.
+ *
+ * That is not a contradiction to reconcile away. The two events describe
+ * different things: this one is the user's intent, the server's is the run's
+ * fate. Counting this as a terminal outcome would under-count completions and
+ * invent a state the database cannot hold — which is exactly what the
+ * predecessor name `web_validation_cancelled` implied.
+ *
+ * `run_id` is null whenever the abort landed before the server replied.
+ */
+export interface ValidationCancelRequestedProperties {
     run_id: string | null;
     validation_mode: ValidationMode;
     duration_ms: number;
     error_phase: ValidationErrorPhase;
 }
+/**
+ * The user was still present when the result rendered.
+ *
+ * Behavioural, never operational. Completion is owned by the backend
+ * finalizer; this records only whether anyone was watching. Keeping the two
+ * apart is what makes both measurable:
+ *
+ *   accepted-run completion rate = server terminal events / submitted
+ *   result observation rate      = this / completed runs
+ *
+ * Fusing them — which is what a browser-emitted `completed` did — yields a
+ * completion rate whose real denominator is "users who stayed on the page",
+ * silently floored by however long the pipeline takes.
+ */
+export interface ValidationResultObservedProperties extends ValidationEventProperties {
+    /** Terminal status the client actually rendered. */
+    run_status: 'complete' | 'error' | 'partial';
+    /** ms from submit to the client rendering a terminal state. */
+    observed_after_ms: number;
+}
 export interface ReportViewedProperties {
     run_id: string;
     validation_mode: ValidationMode;
@@ -322,7 +447,8 @@ export interface AnalyticsEventProperties {
     web_validation_submitted: ValidationSubmittedProperties;
     web_validation_completed: WebValidationCompletedProperties;
     web_validation_failed: ValidationFailedProperties;
-    web_validation_cancelled: ValidationCancelledProperties;
+    validation_cancel_requested: ValidationCancelRequestedProperties;
+    validation_result_observed: ValidationResultObservedProperties;
     report_viewed: ReportViewedProperties;
     report_share_created: ReportShareProperties;
     report_link_copied: ReportShareProperties;
@@ -352,7 +478,7 @@ export interface AnalyticsEventProperties {
     validation_accepted: ValidationSubmittedProperties;
     validation_complete: WebValidationCompletedProperties;
     validation_error: ValidationFailedProperties;
-    validation_cancel: ValidationCancelledProperties;
+    validation_cancel: ValidationCancelRequestedProperties;
     review_saved: {
         run_id?: string;
         review_action: string;

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,
@@ -119,7 +134,8 @@ export const GA_EVENT_NAMES = [
     'web_validation_submitted',
     'web_validation_completed',
     'web_validation_failed',
-    'web_validation_cancelled',
+    'validation_cancel_requested',
+    'validation_result_observed',
     'report_viewed',
     'report_share_created',
     'report_link_copied',

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { RUN_ERROR_CODES, ERROR_CODE_META, mapSnapshotErrorToCode, mapFigmaError
 export type { RunErrorCode, RunErrorMeta, ErrorMapping, RunDisplay, } from './run-errors.js';
 export type { IntakeFramework, UnsupportedStack, UnsupportedReason, UnresolvedReferenceSection, UnresolvedReferenceReason, UnresolvedReference, ParsedThemeColor, ParsedThemeTypography, ParsedThemeSize, ShadcnConfig, ParsedTheme, IntakeDetection, TokenSourceKind, TokenSource, PackageRole, PackageInfo, } from './theme-intake.js';
 export { ANALYTICS_SCHEMA_VERSION, ANALYTICS_EVENT_NAMES, GA_EVENT_NAMES, SECONDARY_EVENT_NAMES, ERROR_CODE_PHASE, FORBIDDEN_PROPERTY_KEYS, errorPhaseFor, isKnownErrorCode, sanitizeProperties, } from './analytics.js';
-export type { AnalyticsSurface, AnalyticsEnvironment, AnalyticsContext, AnalyticsPersonProperties, AnalyticsEventName, GaEventName, SecondaryEventName, AnalyticsEventProperties, AnalyticsPayload, ValidationMode, ValidationErrorPhase, ResultCompleteness, ValidationEventProperties, ValidationSubmittedProperties, ReportShareProperties, ReportShareFailureProperties, WebValidationCompletedProperties, ValidationFailedProperties, ValidationCancelledProperties, ReportViewedProperties, } from './analytics.js';
+export type { AnalyticsSurface, AnalyticsEnvironment, AnalyticsContext, AnalyticsPersonProperties, AnalyticsEventName, GaEventName, SecondaryEventName, AnalyticsEventProperties, AnalyticsPayload, ValidationMode, ValidationErrorPhase, ResultCompleteness, ValidationEventProperties, ValidationSubmittedProperties, ReportShareProperties, ReportShareFailureProperties, WebValidationCompletedProperties, ValidationFailedProperties, ValidationCancelRequestedProperties, ValidationResultObservedProperties, ReportViewedProperties, } from './analytics.js';

package/package.json

@@ -7,7 +7,7 @@
     "The source of truth still lives in the monorepo at packages/contracts/."
   ],
   "name": "@usefidel/contracts",
-  "version": "0.10.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,