Identity

Route flow contract

1. Your managed profile requires an authenticated session. Anonymous users continue through sign-in with return continuation.
2. ensureUserProfileForSession provisions the server profile projection for session entry. That row is not identity authority and must not replace held verified identity.
3. Public route `/<username>` resolves normalized username and loads viewer-aware projection.
4. Private profiles return owner-only detail while preserving public route boundaries.

Identity state assembly

1. Held identity proof supplies continuity. Stored profile fields supply social and contact presentation.
2. Follow relationship is resolved to connection state (`self`, `mutual`, `following`, `follower`, `none`).
3. Originals merge creator-owned records and verified-owned collected records.
4. Anchor metadata resolves claim hash, media envelope, context preset, and download policy flags.
5. Proof verification binds to source bytes and embedded verification material. Stored results and API responses project that evidence.
6. Visibility policy is applied per receiz ID and ownership key, then filtered for public projection.
7. Witness metrics are rolled from analytics and realtime witnessed duration rollups.

Tracked event contract

Event taxonomy is typed and scope-classified (`profile`, `original`, `stream`, `commerce`) before storage.

Windows + timeline ranges

• Every key overview metric includes `all`, `d90`, `d30`, `d7`, `d1` windows.
• Timeline outputs support `30m, 6h, 24h, 7d, 30d, 90d, 1y, 3y` ranges for short-term and long-horizon analysis.
• Profile Analytics renders these ranges with interactive chart switching.

User-facing analytics surfaces

• Managed profile inline stats (followers, witnesses, streams, views, completion, witnessed seconds) with periodic and realtime refresh hooks.
• Profile Analytics gives owners the full console for funnel, top originals, traffic intelligence, and multi-range charts.
• Per-original detail viewer instrumentation for impressions, opens, stream actions, download clicks, and paid flow transitions.

Developer instrumentation notes

• Ingestion endpoint: `POST /api/profile/analytics/track` with strict event-name validation and bounded payload fields.
• Client helper: `trackProfileAnalyticsEventClient(...)` uses sendBeacon/fetch fallback and session dedupe via `oncePerSessionKey`.
• Server aggregation: `loadProfileAnalyticsForOwner(...)` computes overview, stream, commerce, funnel, traffic, timelines, originals, recent activity.
• Schema support: `user_profile_analytics_events` plus `user_profile_witnessed_rollups` trigger-based duration aggregation.
• Realtime publication exists for analytics events and witnessed rollups to support live profile stat freshness.

Data model primitives

Hard constraints to enforce

• Username contract: ^[a-z0-9_]{3,24}$, lowercase canonicalization, reserved-word rejection.
• Profile patch fields are length-bounded and URL-normalized to http/https only.
• Media + original flows verify content size and SHA-256 before durable publish paths.
• Visibility updates enforce ownership checks and entitlement checks for verified-owned showcase.
• Paid downloads require verified payment session metadata binding before byte release.
• Receiz challenge-confirm purchase flow cryptographically binds buyer intent before paid release execution.
• Derivative media generation (image variants/posters) is size-bounded, validated, and policy-controlled.
• Analytics ingestion validates event enum and bounds payload fields for stable rollup quality.

Example: profile mutation

PATCH /api/profile/me
content-type: application/json

{
  "username": "operator_prime",
  "displayName": "Operator Prime",
  "bio": "Canonical issuer profile",
  "websiteUrl": "https://example.org",
  "socialXUrl": "https://x.com/operator_prime",
  "isPrivate": false
}

Example: analytics event

POST /api/profile/analytics/track
content-type: application/json

{
  "username": "operator_prime",
  "event": "original_open",
  "receizId": "00000000-0000-0000-0000-000000000000",
  "source": "profile_public_page",
  "durationSeconds": 12.4,
  "meta": {
    "ownershipKind": "creator",
    "layout": "single"
  }
}