KYE Protocol™ · v3 Entity Hierarchy

Every entity has one parent and one state machine.

KYE Protocol™ organizes every governed entity in a single containment tree rooted at the Tenant. In v3, Model, Tool, External App, and Audit Stream are first-class entities with their own IDs, state machines, and authority grants — not subtypes of Principal.

account_tree The tree domain Tenant level workspaces Workspace level new_releases v3 changes

1 · The containment tree

One tree. 14 entity classes. No orphans.

Every entity lives at exactly one node. The parent chain is required at every level. You can traverse from any leaf up to the Tenant root in at most four hops.

Tenant                          (kye:tenant:…)    — billing + isolation root
  ├── Legal Entity              (kye:lglent:…)    — registered legal person
  ├── Billing Account           (kye:bill:…)      — Stripe customer + payment
  ├── Domains                   (kye:dom:…)       — verified DNS domains
  ├── Policies                  (kye:pol:…)       — Operating Model™ + rules
  └── Workspaces                (kye:wsp:…)       — environment / dataspace
        ├── Projects            (kye:prj:…)       — units of work
        ├── Teams               (kye:team:…)      — RBAC + ownership group
        ├── Resources           (kye:res:…)       — datastore / object store / queue / connector
        ├── Principals          (kye:prin:…)      — Human / System / Agent
        ├── Models              (kye:model:…)     — inference artefacts (v3)
        ├── Tools               (kye:tool:…)      — named callables (v3)
        ├── External Apps       (kye:extapp:…)    — 3rd-party integrations (v3)
        └── Audit Streams       (kye:audstream:…) — event destinations (v3)

Each entity also carries a state field and a state_machine_id. See State Registry™.

2 · Tenant level

Five siblings directly under the Tenant.

The Tenant is the billing and isolation root. Its five siblings are independent — they do not nest inside each other.

Legal Entity kye:lglent:…

The regulator-facing registered legal person. One Tenant may hold multiple Legal Entities (group structure, foreign subsidiaries).

Billing Account kye:bill:…

Stripe customer ID, payment method, billing email, tax ID, currency. One Tenant may hold multiple Billing Accounts (split billing per business unit).

Domain kye:dom:…

A verified DNS domain the Tenant owns. Used for branded sender, federation routing, and SSO.

Policy Bundle kye:pol:…

Active Operating Model™, rule bundles, attestation policies, and sub-processor list. One Tenant may hold multiple bundles (one per regime: PRA / DORA / EU AI Act).

Workspace kye:wsp:…

Environment or dataspace. One Tenant may hold many Workspaces (prod, sandbox, eu-west-1, consumer-bank, corporate-bank).

3 · Workspace level

Eight siblings inside every Workspace.

The Workspace is the environment boundary. Every entity below it is scoped to that Workspace — its authority grants, state machines, and audit events are all Workspace-local unless an explicit cross-Workspace grant exists.

Project kye:prj:…

A unit of work with a scoped budget and quota. One Operating Model fragment per Project.

Team kye:team:…

RBAC and ownership group. Controls who owns what, defines the bounded delegation surface, and routes approvals.

Resource kye:res:…

A datastore table, object-store bucket, queue, or connector owned by the Workspace. Resources are leaves — they do not contain other entities.

Principal kye:prin:…

The acting party in a Decision Map™. In v3, Principal subtypes are: human, system, agent. Model, Tool, and External App are now separate entity classes.

Model v3 kye:model:…

A versioned inference artefact (LLM, vision model, embedding model). Carries provider, family, version, and weights_hash.

Tool v3 kye:tool:…

A named callable (function, MCP tool, API endpoint). Carries function_signature, declared_capabilities[], and side_effects[].

External App v3 kye:extapp:…

A 3rd-party integration or partner connector acting on behalf of the Tenant. Carries partner_org_id, connector_kind, and oauth_subject.

Audit Stream v3 kye:audstream:…

An append-only event-log destination (SIEM, S3, Splunk, Kafka topic) the Workspace writes to. Governed by an authority grant, not an IAM binding.

4 · v3 changes

What changed from v2 to v3.

In v2, Model, Tool, and External App were subtypes inside the Principal entity via the principal_class field. In v3 they are first-class entities with their own IDs.

Model, Tool, External App removed from principal_class enum. A kye:prin:… entity in v3 has principal_class of human, system, or agent only.
Agent Principals reference Models and Tools by entity ID. An agent's record holds model_entity_id (a kye:model:… URN) and tool_entity_ids[] (a list of kye:tool:… URNs).
Audit Stream added. A new class kye:audstream:… for append-only event destinations.
Relationships are explicit edges. The five canonical edges (member_of, acts_in, granted_access_to, uses, applies_to) are stored as kye:rel:… records, not inferred from nesting.
Migration window. Existing tenants have until 2026-08-14 to migrate v2 Principal records to the new classes. Both representations are valid during the window.

Learn more about entity relationships: Vocabulary.