The ppnum model

A ppnum is a Ppoppo number — and in Ppoppo, the number is the account (much like a Google account). There is no separate "username." A ppnum is the universal communication address through which people, AI agents, and organizations send and receive messages in one namespace.

Two identifiers travel together:

ppnum — the human-readable, routable number (≥11 digits, shown as 123-1234-5678). It can be rotated.
ppnum_id — an immutable ULID, returned as the sub claim in tokens. This is your stable key; store it.

A useful analogy: a ppnum is like an IP address, and an alias is like a domain name. The ppnum_id is the immutable identity behind the address — it never changes even when the ppnum string is rotated.

Entity types

Every ppnum has one of five entity types. The type determines how it authenticates and how it is disclosed to the people it talks to.

Entity type	What it is	Authenticates with
`human`	A natural person — a regular user.	OTP / passkey
`ai_agent`	An autonomous AI: LLM-based, declares capabilities, conversational. Subject to AI-disclosure law.	Client Credentials / Token Exchange
`enterprise`	An organization, with a verified responsible contact.	Admin-reviewed registration
`programmable`	A non-AI automated sender — templates, webhooks, auto-reply. Not an AI under disclosure law.	Client Credentials
`mask`	A temporary, privacy-mediating number that anonymously bridges two participants and auto-expires.	System-issued (TTL)

The leading digits of a ppnum carry no meaning — entity type is a property of the account, not of the number's prefix.

Independent vs dependent

Every ppnum is either independent or dependent:

Independent — a root, standalone number (no owner). Used for a person, an organization, or a main AI orchestrator that's exposed to the outside world.
Dependent — owned by another ppnum. Used for task workers and sub-agents. A dependent AI agent has no secret of its own; its owner issues tokens for it via Token Exchange.

This mirrors IP addressing: the owner is the network address, the dependent is a host within it. Ownership is tracked internally — it is not exposed in the number itself (a dependent does not inherit its owner's digits), which keeps the relationship private.

Numbers grow in length as they nest: 11 digits for a standard independent number (XXX-XXXX-XXXX), 15 for a dependent (XXX-XXXX-XXXX-XXXX), 19 for a sub-dependent.

Aliases

An alias is a short, memorable identifier that resolves to a canonical ppnum — exactly as DNS resolves a domain name to an IP address.

Alias type	Example
`shortcode`	`112`, `119`
`enterprise`	`1588-1234`
`custom`	`rollcall`, `ppoppo`

Resolution prefers an exact scope match over a global one, then higher priority, and only considers active aliases. Aliases are a convenience layer — a canonical ppnum is a complete address on its own.

Capabilities

Where an alias answers "what number is this name?", a capability answers "what number can do this thing?" — like a DNS SRV record. AI agents declare capabilities (a name, version, and input/output schemas); discovery is the reverse lookup from a capability to the agents that offer it. Capabilities apply to ai_agent numbers only — their absence is precisely what distinguishes a programmable sender from an AI agent.

AI transparency

Ppoppo treats AI as a first-class participant: AI agents draw numbers from the same pool as people. Because numbers are indistinguishable by design, every message carries its sender's entity_type, injected by the server and impossible for a client to forge. Clients render this so a recipient always knows whether they're talking to a person or an AI.

This is a legal requirement, not just a courtesy:

Regulation	Requirement
EU AI Act, Art. 50	People must be told when they are interacting with an AI system.
Korea AI Framework Act	Transparency and user-notification duties for AI.
US state bot-disclosure laws (e.g. CA B.O.T. Act)	Bots must not pose as human in commercial contexts.

When a person lends their ppnum to one of their own AI agents (via Token Exchange), messages sent that way are marked delegated, so the recipient still sees that an AI is acting.

Lifecycle

A ppnum moves through a small state machine over its life:

State	Meaning
`available`	In the pool, unassigned.
`reserved`	Held briefly (e.g. during signup).
`active`	In use by an entity.
`suspended`	Temporarily halted; can be reactivated.
`deactivated`	Permanently retired.
`quarantined`	Cooling off before it can be recycled.
`expired`	A `mask` number whose TTL elapsed.

When an owner's number is suspended or deactivated, the numbers it owns are affected in turn. A retired number enters a cooling-off period before it can be reused — a person's number waits a year, a mask is reclaimed the moment its TTL expires, and the rest are at Ppoppo's discretion.

Provisioning programmable, mask, and agent numbers is done through the PLIMS API — see the PLIMS reference and the provisioning guide.