arizuko › concepts › primitives

primitives

arizuko is an event→reaction engine: something happens, an agent reacts. The whole system is six small parts in a fixed order, plus one coordinate system they’re all addressed in. Everything else — channels, tasks, webhooks, secrets, delegation, workflows — is those parts recombined, not new machinery.

Trace one event

The fastest way to see the shape is to follow a single Slack mention from the moment it arrives to the reply going back out:

Slack @mention in #eng
  → Event          one inbox row (messages.db)
  → Routing        → corp/eng/oncall
  → Agent          folder loaded: persona, skills, memory
  → Authorization  may it read / send / delegate here?
  → Turn           one ephemeral container run, then it exits
  → State          rows written, files edited
  → reply in the Slack thread

It looks like feature sprawl until you trace one example — then it’s six steps, every time.

The six primitives

• Event — the one inbox. A chat message, a webhook POST, an inbound email, a WebDAV file drop, a scheduled tick, a reaction: all land as one row in messages. The channel adapters, emaid, webhooks, timed, davd are all just event sources writing rows.
• Routing — event to folder. One route table, first match wins, with a few layers on top: direct address, engagement (keep listening after a mention), sticky topics, observe (ingest, don’t reply). Delegate and escalate are routing to a child or parent folder. See routing.
• Agent — who reacts, and with what knowledge. An agent is a folder: PERSONA.md, skills/, MEMORY.md, a diary, an ACL. The org chart is the folder tree (corp/eng/sre, any depth). See the ant.
• Authorization — one question: may this principal do this action here? Defaults live in code per tier; the operator overrides with rows in the acl table. See grants and scopes.
• Turn — the bounded reaction. One ephemeral Docker container runs the agent loop for a single turn, then exits. Every side effect is one tool call through the auth gate, written to one audit row. Tasks, autocalls, and interjections are all just turns triggered by a different event.
• State — what persists, in two stores by design. The shared database holds events, routes, grants, ACL, sessions. The folder on disk holds the persona, skills, memory, diary. The folder is not a cache — containers are stateless and mount it each turn. A tar of the instance directory is a full backup. See secrets.

Identity — the coordinate system

Identity isn’t a step in the pipeline; it’s the coordinate system the six steps are addressed in. Subs, JIDs, folders, tiers, scopes. Routing resolves to a folder, authorization keys on a principal, a turn runs as agent:<folder>, state is partitioned by folder — every primitive refers to identity, none sequences it. See auth and addressing.

Workflows — a discipline, not a primitive

A multi-step job thrashes when the agent re-improvises from chat scrollback every turn. The fix isn’t a workflow engine: it’s making the session boundary run a fixed opening — load context, open a plan file, apply the folder’s runbook, scan skills — before the agent free-associates. Conversation stays free; the opening gets strict. That’s Turn + State + the session lifecycle, not new machinery, so it’s a recomposition too.

No special cases

This is the proof that the surface is small: every “feature” is one of the six recombined.

The four layers

The same small set of concepts stacks into the things you deploy and ship. This is what arizuko is about: primitives become packages become processes become products.

A product sits at the bottom: the same pipeline, a different folder. That’s why a support agent and a personal life agent run the same code. The components section lists the daemons (you deploy daemons, not packages, so the site shows three layers; the package layer is named in the README).