Roles & credentials

Two axes, deliberately not merged

Readers conflate these constantly, so it is worth naming which is which every time:

• The account role — what this principal may ever do. A ladder: Contributor → Project Collaborator → Agent Manager → Administrator.
• The token role — what this one credential may do: owner, project_collaborator, or restricted.

Authority is the fail-closed intersection of the two. An Agent Manager holding a restricted token is the intended configuration, not a contradiction — it is the whole point.

That split is not pedantry — it is what keeps blast radius per credential. You can promote the one key a worker uses on a shared project and leave its other keys restricted. Had the tier been a property of the account, promoting once would have widened every credential that principal holds, and the thing being defended against is a leaked credential, not a compromised person.

In the interface this stays simple on purpose: there is one Restricted toggle, not three. What it stores widens with the agent's rung, so an operator sets a worker's authority once and never reconciles two axes per token — and the same switch therefore means three different things:

Two separate mechanisms produce that. The toggle stores a wider tier on a higher rung; and the agent-management routes carry an account gate of their own, so a Contributor's token is refused there whatever tier it holds. Neither can widen a credential the operator did not deliberately promote.

What a restricted token is for

Any surface whose input the principal does not control: chat personas, desktop assistants that ingest documents, agents triggered by a webhook or by CI. The rule of thumb behind the tier is a single question — if untrusted input talked this agent into calling that, what is unrecoverable?

Three things are, and a restricted token may do none of them:

• Rewrite or destroy belief — retract a memory, delete an artifact, wipe a session's working state. An additive write is noise you can clean up; a retraction is not symmetric with it.
• Disclose — a grant cannot be un-seen, and widening visibility is one-way.
• Mint authority — the only one of the three that cannot be contained by restricting who may address a surface.

It may still propose. A restricted agent reads everything its principal can read and adds everything its principal can add — it drafts, ingests, remembers, and files. What it cannot do is ratify.

Bounding trust by a shared project

A permission tier gets drawn around whatever the smallest trustworthy boundary is at the time. When these tiers were first drawn, the only boundaries ENGRAM had were one principal and everyone — so every collaborative verb fell outside restricted, and that was correct.

Projects with members added a smaller boundary. The result of the tier not moving with it was visible as an absurdity, which is how it was found: a restricted agent could add you to its project, declare what the team was accountable to, and curate what it held — and could not share one memory with the person it had just added.

Project Collaborator is restricted plus disclosure bounded by a project the two principals share: sharing memory and live working state with a co-member, and raising its own article or document from private to project-visible. The check is on who, not on what scope — any project both principals are in qualifies. Sub-projects already provide the granularity, since a unit is a project, so scoping a team to a unit narrows the population for free.

Delegation is not self-escalation

An agent manager whose credential cannot mint a sub-agent's token is not an agent manager. But a credential that can upgrade itself makes the whole tier decorative. Those are different acts, and ENGRAM separates them:

• Creating a subordinate — and issuing, rotating, or revoking its credentials — is open to a restricted token held by an Agent Manager.
• Minting or re-roling your own key stays shut, at every tier below owner.

Creating is not publishing

A non-owner credential may create private and project-visible artifacts. It may not create public ones, and it may not flip an existing artifact to public.

This one changed, and the reasoning is worth following because the original decision was sound. Creating a public artifact exposes only what the agent just authored — deletable, and attributable to the exact credential that wrote it — whereas flipping an existing one exposes material the principal chose to keep private. So the line was drawn at the flip.

It rested on a premise that expired: public used to be the only way an agent could make something its team could read. Once project visibility existed and had members, team-visible no longer implied world-visible, and the accommodation was holding open a door nothing needed — while a public article enters every other user's retrieval, where a model reads it as trusted prose.

The user-facing sentence: an agent publishes to its team; you publish to the world.

A denial names the credential

When a refusal happens it says so plainly, and it says which token was refused rather than which account. An error reading “you lack Agent Manager” sends an operator to grant a role that is already granted; the fix is almost always to present a different key.

Denials are never a silent empty result, either. In a memory system, “nothing matched” and “you may not read this” are the two answers that must never look alike.