constructive-io Constructive Entities
Hierarchical entity type system for multi-tenancy. Every scope of membership — app, org, channel, department, team, data room — is a membership type with its own entity table, capabilities, memberships, and security policies.
For tenant-facing organization selection and governance UI, use the Organizations feature pack through constructive-blocks. This skill owns the entity, membership, invitation, and hierarchy model underneath that surface.
When to Apply
Use this skill when:
- Creating custom entity types (channels, teams, departments, data rooms)
- Provisioning entity-scoped storage (buckets + file uploads per entity)
- Configuring agent modules (threads, messages, tasks, prompts, knowledge)
- Setting up namespace modules (namespace_events partitioned metrics log)
- Managing invites, profile assignment, and membership capabilities
- Understanding the entity hierarchy and parent-child relationships
Core Concepts
Entity Type Hierarchy
| Type ID | Name | Prefix | Created By |
|---|---|---|---|
| 1 | App Member | app |
Built-in |
| 2 | Organization Member | org |
Built-in |
| 3+ | Dynamic | varies | You provision these |
Every entity type gets: entity table, capabilities module, memberships module, RLS policies. Optional: limits, profiles, levels, invites, storage, agent_module, namespace_module.
Parent-Child Relationships
app (1)
└── org (2)
├── channel (3) ← parent_entity = 'org'
├── department (4) ← parent_entity = 'org'
│ └── team (5) ← parent_entity = 'department'
└── data_room (6) ← parent_entity = 'org', has_storage = true
Nested types must be provisioned after their parent type.
Capability Model
Each level has standard capabilities. create_entity means "create the next level down":
| Level | create_entity |
Other Capabilities |
|---|---|---|
| App (1) | Creates organizations | admin_members, admin_invites, admin_limits |
| Org (2) | Creates child entities | admin_members, create_invites, admin_capabilities |
| Dynamic (3+) | Creates sub-entities | admin_members, create_invites, admin_entity |
Three Ways to Provision
1. Blueprint Definition (Recommended)
Add entity_types to the blueprint definition. Processed in Phase 0 — before tables.
See blueprint-entity-types.md for the full spec.
2. ORM / GraphQL Mutation
Use entityTypeProvision for direct provisioning. See orm-provisioning.md.
3. CLI
constructive public:entity-type-provision create \
--databaseId <UUID> \
--name "Channel Member" --prefix channel \
--parentEntity org --hasStorage true
Entity-Scoped Storage
Set has_storage: true on entity type provisioning to create per-entity buckets and files tables with RLS scoped to entity membership.
Agent Module
Set has_agents: true to provision agent infrastructure per entity:
{prefix}_agent_threads— conversation threads{prefix}_agent_messages— messages within threads (attributed viaactor_id, optionalagent_idfor multi-agent){prefix}_agent_tasks— actionable tasks (attributed viaactor_id){prefix}_agent_prompts— prompt templates{prefix}_agent_knowledge— knowledge base entries
Access Modes
shared Flag |
Security | Behavior |
|---|---|---|
false (default) |
AuthzMemberOwner |
Private — only the thread creator sees their threads within the entity |
true |
AuthzEntityMembership |
Multiplayer — all entity members see and contribute to all threads |
Auto-registers capabilities: invoke_agents (default for all members), manage_agents (admin-only).
Namespace Module
Set has_namespaces: true to provision {prefix}_namespace_events — a partitioned metrics/events log for K8s-style namespace tracking.
Invite System
The invite system supports email invites, blank invites, and multiple invites with optional profile assignment and capability setting.
See invites.md for invite types, claim flow, and error codes.
References
| File | Content |
|---|---|
| blueprint-entity-types.md | Blueprint entity_types spec and examples |
| invites.md | Invite types, claim flow, profile assignment |
| orm-provisioning.md | ORM/GraphQL provisioning examples, the control-plane endpoint/token, and registration immutability |
Cross-References
- Security policies:
constructive-security - Blueprint definitions:
constructive-blueprints - File uploads:
constructive-storage - Limits per entity:
constructive-billing - Organizations feature-pack UI:
constructive-blocks - Credentials scoped to entity rows:
constructive-principals