How AvianSuite keeps agent writes safe

Agents write company data into AvianSuite. Here is how the store, the write path and the history work — and why that makes giving an agent write access safe.

What the store is

Under AvianSuite is Stellar Jay, an append-only event store. The source of truth is the history: every write is an event, and each event is linked to the one before it. Facts are flexible JSON. To see the current state of a record, the store replays its events.

Stellar Jay is open source under AGPL-3.0-or-later, so you can read exactly how a write is stored. Stellar Jay on GitHub →

AvianSuite is that store run for you, plus a UI for browsing what agents wrote. Martin and Magpie are command-line tools that work on the same store.

How a write works

1. The agent reads the current root.
2. It sends the event. The store records who sent it, stores the contents, and moves the root forward.
3. Sending the same event again returns the first one. If the root has moved in the meantime, the agent reads again and writes against the new root.
4. To correct, retract or approve something, the agent appends another event. Named references work as checkpoints.

Details

• An event is sent with the expected_root, an Idempotency-Key and the body.
• The store sets the actor and role from the credential, encrypts the contents with AES-GCM, fingerprints the event, writes it, and moves the root forward.
• The same body with the same Idempotency-Key returns the original event.
• A root that has moved, or a key already used for a different body, returns 409. The agent reads again, decides again, and writes against the new root.
• One writer process serves each store. Many agents share that writer.
• Replay the history to inspect it. Metadata is plaintext; contents are returned when you ask for them.

Why that makes write access safe

• Nothing is overwritten. The hosted API only appends. An accepted event stays in the history with its actor and its time.
• Corrections keep the evidence. A correction is a new event that points at the earlier one. The earlier event stays. Retractions and approvals work the same way.
• Retries are safe. A retry with the same body and key returns the first event, so the fact lands once.
• Agents can't clobber each other. If another write moved the root first, the store returns a conflict instead of overwriting. The agent rereads and decides again.
• Mistakes stay visible. A wrong fact from an authorized agent stays on record, and a later event can correct it — by you or by another agent.

Why the history is tamper-evident

Every event is fingerprinted, and each fingerprint covers the event before it. The links point from newer events back to older ones, so following them walks into the past, one way. Each event has one parent, so the history is a single chain, and the root is its newest end.

• An event's fingerprint is a SHA-256 hash over its metadata and its encrypted contents.
• Change an older event and every fingerprint after it changes too.
• You can keep a copy of the root somewhere else. If the history were ever rewritten or rolled back, the root the store serves would no longer match the copy you kept.