arizuko › concepts › scopes

scopes

A grant names a scope, the S in “can P do A on S”, and that scope is a folder path. The same folder tree also decides what each agent can see. Messages inside a folder are its own conversation. Messages in a sibling folder appear as ambient context that the agent reads without a request. Messages in a child folder stay isolated. So the tree you build for permissions also limits the context.

A folder is a scope

Every group is a folder under the data directory: solo/inbox, corp/eng/sre, corp/eng/oncall. The folder path is also the identity of the agent that runs there, and the value that the scope glob of a grant matches. Depth gives no authority. A “world” folder such as corp/eng is an ordinary tenant, and it can do what the acl rows that name it allow. Siblings share a parent.

One agent runs per group. The corp/eng/sre agent keeps its own conversation history, diary and skills, and corp/eng/oncall keeps its own.

Files and grants read one path tree in two ways

A few names first. A folder is one agent. A group is a folder that routd knows. A world is a top-level folder, such as corp. A chat is one JID, the room where people talk. A route sends a chat to a folder. Many chats can reach one agent, and each topic in a chat has its own session.

The folder path corp/eng/sre is one tree, and arizuko reads it in two ways:

read as files                         read as grants
groups/corp/                          a row on corp/** covers:
├── PERSONA.md      corp only           corp, corp/eng, corp/eng/sre
├── share/          the world dir
└── eng/                              a row on corp/eng/** covers:
    ├── PERSONA.md  eng only            corp/eng, corp/eng/sre
    └── sre/
        └── PERSONA.md  sre only      depth alone gives no grant

As files, each folder has its own

The directory of a child is inside the directory of its parent: groups/corp/eng/sre/ is in groups/corp/eng/. A turn mounts the folder of its agent as home. So the agent of a parent can read and write the files of its whole subtree: the memory, the diary, the facts, the skills and the persona of each child. Nothing goes down the other way. routd reads the PERSONA.md of the turn folder only, and each group gets its own skills, so a child takes no file from its parent.

As grants, a path covers its subtree

An acl row with the scope corp/eng/** covers corp/eng and every folder under it. A holder can grant others only a subset of what it holds, and only with the grant option. Egress allow rules add up along the path: a rule on a parent opens the host for every descendant. All groups of a world share one directory, /var/lib/share in the guest.

Siblings see each other

Two folders under the same parent see each other’s messages as ambient <observed> context on every turn. The default sibling list is every folder with the same immediate parent. So corp/eng/sre and corp/eng/oncall each see the traffic of the other.

The agent sees a limited part of the sibling messages, not all of them. OBSERVE_WINDOW_MESSAGES and OBSERVE_WINDOW_CHARS set the instance default. routes.observe_window_messages and routes.observe_window_chars override it for one route.

Children are isolated

A child folder is not a sibling. corp/eng/oncall/incident-42 sits under oncall. The parent does not see the child automatically, and the child does not see the siblings of its parent. To connect them, route the traffic of the child up with a routing rule, or grant a specific ACL across the folders.

An incident folder stays quiet for its parent

corp/
  eng/
    sre/         ← sees oncall (sibling)
    oncall/      ← sees sre (sibling)
      incident-42/   ← isolated; oncall does not auto-see it

An SRE who asks a question in corp/eng/sre sees recent oncall messages as ambient context. An incident lead in corp/eng/oncall/incident-42 talks only to the agent of the incident folder.

Each topic has its own observed cursor

Inside one folder, every topic keeps its own position in the observed messages. So #triage and #deploy in the same folder both see the same ambient messages, and one topic does not use them up for the other. The cursor is per pair of folder and topic, in sessions.observed_cursor.

Topics and routing explain the rest

topics covers topic lineage and the observed cursor of each topic. routing covers how a message reaches a folder.