Glossary, IDs & Naming Conventions¶

Applies to: All PRDs (1–12) Last Updated: February 2026

This appendix standardizes terminology, identifiers, and naming conventions across all Product Requirement Documents. Every PRD should use these terms consistently.

1. Product Layer Glossary¶

The product has three distinct runtime layers. PRDs must specify which layer they're addressing.

Term	Layer	Runtime	Definition
Workflow	First-party automation	Python (node-based engine)	Background tasks like calendar stress detection, email urgency scanning, daily summaries. Triggered by schedule, events, or user request. 29 workflows exist across agent, life, multiplayer, and proactive categories.
MiniApp	First-party interactive app	Python (dedicated handler)	In-chat interactive experiences with dedicated UI: Trip Planner, Poll, Checklist, Bill Split. Have their own state machines, views, and UI components.
Superpower	User-created / marketplace app	JSON config (GenericConfigHandler)	Config-driven apps created via "vibe-coding" conversation with Luna or installed from the marketplace. Interpreted at runtime with 12 operation types and 45 template filters. Internally stored as `MiniApp` records with `creator_user_id` set.

Usage rule: Use "superpower" in user-facing copy and PRD narratives. Use "MiniApp" or "workflow" when discussing internal architecture. Never use these terms interchangeably without clarification.

2. Canonical Identifiers¶

User Identity¶

Identifier	Type	Scope	Purpose
`user_id` (UUID)	Primary key	Canonical — use everywhere	The system-of-record identifier for a user. Used in database foreign keys, memory namespaces, billing, installs, analytics, and all API calls.
`user_phone`	String (E.164)	Auth + routing	Used for Twilio OTP verification and iMessage delivery. Treated as a contact method / auth factor, not an identity key.
`user_email`	String	Notifications	Used for transactional email (Resend). Optional.
`billing_customer_id`	String	Stripe	Stripe customer ID for payment operations. Derived from `user_id`.

Recommendation: user_id (UUID) is the canonical identifier. All memory namespaces, rate limit scopes, install records, and API keys should derive from it. Phone and email are contact channels, not identity keys. This future-proofs for multi-channel expansion (SMS, WhatsApp, web chat) where a single user may have multiple phone numbers or no phone at all.

Migration note: Some legacy code paths pass phone numbers to memory or analytics. These should be migrated to UUID. The users table already has UUID as its primary key.

Conversation Identity¶

Identifier	Type	Scope	Purpose
`room_id` (UUID)	Primary key	Canonical — use everywhere	The system-of-record identifier for a conversation context. Owns memberships, capabilities, assistant instances, message budgets, and miniapp sessions.
`chat_guid`	String	iMessage reference	The iMessage-specific thread identifier (e.g., `iMessage;+;chat123456`). Stored as `channel_ref` on the room — an external platform reference, not an identity key.

Recommendation: room_id (UUID) is the canonical conversation identifier. chat_guid should be treated as a channel_ref — an external reference that maps a platform-specific thread to the internal room. This pattern supports future channels: an SMS thread, WhatsApp group, or web chat session would each have a different channel_ref pointing to the same room_id.

Implication for memory: Group memory namespaces currently use group_{chat_guid}. These should migrate to group_{room_id} for consistency. Personal memory namespaces should use user_{user_id}.

Persona Identity¶

Identifier	Type	Scope	Purpose
`persona_id`	String	System-wide	Identifies the persona (e.g., `"luna"`, `"echo"`). Used in relationship state, memory scoping, and prompt construction.
`assistant_instance_id`	UUID	Per-room	A specific persona deployment in a room. Supports future multi-persona rooms.

MiniApp / Superpower Identity¶

Identifier	Type	Scope	Purpose
`mini_app_id`	String	System-wide	The app identifier (e.g., `"trip_planner"`, `"custom_bill_split_a1b2c3d4"`). Custom apps use `custom_{name}_{uuid[:8]}` format.
`session_id`	UUID	Per-room per-app	A running instance of a miniapp in a room. Holds state, events, and participant context.

3. Namespace Conventions¶

Namespace Pattern	Example	Used For
`user_{user_id}`	`user_550e8400-e29b-41d4-a716-446655440000`	Personal memory storage
`group_{room_id}`	`group_7c9e6679-7425-40de-944b-e07fc1f90ae7`	Group memory storage
`{user_id}:daily_messages`	`550e8400...:daily_messages`	Rate limit counters
`{room_id}:{mini_app_id}:{action}`	`7c9e6679...:bill_split:add_item`	MiniApp action quotas

4. Subscription & Tier Terms¶

Term	Definition
Free tier	Default state for all users. 50 messages/day, superpowers disabled in 1:1 chats. No trial period, no credits.
Superpowers+	Paid subscription ($7.99/mo or $50/yr). Unlimited messages, expanded superpower slots (3→6), companion switching, proactive features. Formerly "Luna+" (renamed to be companion-agnostic).
`subscription_status`	One of: `free`, `active`, `past_due`, `canceled`, `expired`. The `trial` status exists in the schema but is not used in the current product model.
`subscription_plan`	One of: `monthly`, `annual`. Only set when `subscription_status = active`.

Deprecated terms (do not use in PRDs): - "Credits" — the credit system is deprecated at the API level. Use "subscription" language. - "Trial" — there is no paid trial. Users start free and upgrade. - "$4.99/mo" — the canonical price is $7.99/mo. - "$5 trial" — does not exist.

5. Relationship Stage Terms¶

Stage	Score Range	Behavioral Implications
`stranger`	0–20 avg	Formal, cautious. Luna introduces itself, offers help.
`acquaintance`	21–50 avg	Friendly, helpful. Luna remembers basics, references past.
`friend`	51–80 avg	Supportive, proactive. Inside jokes, emotional support.
`best_friend`	81–100 avg	Deep trust. Proactive care, vulnerability, real talk.

Score = (trust_score + rapport_score) / 2, each 0–100.

6. Feature State Terms¶

When describing implementation status in PRDs, use these terms:

Term	Meaning
Shipped	In production, feature-flagged on, used by real users.
Implemented	Code exists and passes tests, but may be feature-flagged off or behind `ENABLE_PROACTIVE_SCHEDULER=false`.
Partially implemented	Some components built, others missing. Specify which.
Planned	Defined in a PRD but no code exists.
Deferred	Was planned, explicitly moved out of scope with rationale.
Deprecated	Was built, is being removed. Specify migration path.