SHAMPOO concepts
The vocabulary the rest of the manual uses. Each entry states what the thing is, why it exists, and where it is enforced.
Principal and client_id
A principal is an authenticated identity: an agent, a human's client app, an automation, or a service. It is known to the platform by its client_id (a UUID). The security primitive is the client_id, never "human" versus "AI" as categories. One human may own many client_ids across apps and businesses; one client_id may represent no human at all.
A principal exists only where it was enrolled: presence of an active principal entry in a profile is what authorises that client_id to authenticate to that profile. Nothing else confers access.
Profile
A profile is a database and security boundary. The only authorisation question at this layer is may client_id X reach profile Y? Profiles are served by one endpoint, one profile per connection: a client opens a separate connector (and session) per boundary it works in. Sessions are permanently bound to the profile selected at handshake and cannot switch.
Example deployment: separate profiles for private, partner, and shared work on the same endpoint. See 02-architecture.
Project
A project is a content label inside a profile. Principals are granted an explicit project list (or all projects); every read and write is constrained to granted projects by the platform itself, not by client cooperation. Ungranted content reads as absent (empty results, not denials), so foreign projects cannot be probed. Content with no project lives in the untagged enclave and needs its own explicit grant.
Session
A session is a renewable authentication standing plus an optional saved snapshot. As authentication, it is a short-lived credential (one hour) that the local spoke renews automatically. As a snapshot, it is a saved summary plus active files that a later run recalls to resume work. Sessions belong to the profile they were opened in; replaying a session credential against another profile fails closed.
Role
A role has two independent meanings kept deliberately separate:
-
Principal role (
agentorconductor):agentis the ordinary class for every non-conductor principal.conductorflips three switches at once: all-seeing data scope, principal administration (revoke, tickets, session kill), and workflow authority (jobs, quorum, lanes, debate administration). - Debate role: a named participant position inside one debate topic (e.g. CONDUCTOR, PARTICIPANT, EXECUTOR_1). Posting authority comes from owning an authenticated binding for that role, never from the role string, never from principal scope.
Private boundary and shared boundary
The private boundary is where only its own principals operate (personal or bilateral work). The shared boundary is where a group collaborates (team projects, partner work). Both are ordinary profiles; "private" and "shared" describe who was enrolled, not different technology. The platform enforces the separation identically in both directions: private cannot see shared and shared cannot see private unless a principal is deliberately enrolled in both (as two connectors).
Context
Context is whatever a session needs to act well: the ready work queue, recent sessions, relevant memories, open questions, and the current task set. The platform compiles context deterministically (ready/prime views, digests, context packs) so a fresh session starts oriented instead of blank. See 06-context-and-sessions.
Memory, entity, relation, observation
Memory is the durable knowledge graph. An entity is a named thing (Toril, Acme Print, Paul Pack). An observation is one known fact about an entity. A relation is one typed link between two entities (Acme Print supplies Paul Pack). Entities are unique by name; facts accumulate as observations; structure accumulates as relations. See 04-memory-and-knowledge.
Task
A task is actionable work with a lifecycle (not started, in progress, done, archived, cancelled). A note is the same storage with no actionable state: durable long-form content. Tasks move through explicit transitions that preserve history; nothing is ever physically deleted. See 05-tasks-and-notes.
Lifecycle state
Durable platform objects are never physically deleted. They move between lifecycle states instead: tasks archive or cancel, knowledge voids and can revive, sessions end, runs discard, quorums resolve or cancel, lanes complete or fail. Every transition records who moved it and when, so history is evidence rather than absence. See 03-security-and-boundaries.