@usefidel/contracts 0.10.0 → 0.11.0

package/dist/analytics.d.ts

@@ -112,7 +112,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,7 +125,7 @@ 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;
@@ -179,7 +179,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 +219,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 +265,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 +292,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 +399,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 +430,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

@@ -119,7 +119,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.11.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,