Studio · Principle

Semantic Events as Platform Primitive

A platform contract for declared events. Less analytics, more nervous system.

The primitive

Every serious platform has a quiet superpower: years of declared relationships sitting in tables. Then we bolt on AI and ignore them. That is the mistake.

If you want trustworthy answers, you need a trustworthy substrate. Not vibes. A contract. Here it is: declared events as a platform primitive.

Nine fields
The event schema 9 fields
  1. 01 event_id The permanent receipt. A stable, globally unique identifier. This is what you reference when you want to trace a chain of causality. Without it, you have logs. With it, you have provenance.
  2. 02 event_type The vocabulary of your platform. A noun for a verb your system performs: "permission_checked", "approval_submitted", "rollup_computed", "integration_applied". This is what makes events searchable and categorizable across the whole system.
  3. 03 timestamp When it happened. Always UTC. Without this, causality analysis breaks down entirely.
  4. 04 actor Who did it. Not just a user ID, a typed entity. The type field distinguishes a human user from an automated service, an AI agent, or a scheduled job.
  5. 05 target What it happened to. Same pattern as actor: a typed entity with a stable ID. The target is what you retrieve when you ask "show me everything that ever touched this record."
  6. 06 decision What the system concluded. Three possible outcomes: allow, deny, mutate. The policy_fingerprint is a hash of the exact rule set version evaluated. Events from today still point to the policy in force when they happened.
  7. 07 evidence What the system looked at. The rules it evaluated and the relationship graph it traversed. The difference between "denied" and "denied because of these specific rules, applied to these specific relationships."
  8. 08 causality The chain. Every event points to what triggered it and what it triggered in turn. This is how you reconstruct sequences, not by inferring from logs, but by following declared links.
  9. 09 access_boundary The permission context. Two fields: principal and scopes. Principal names the authority under whose identity this request is made. Scopes are what that principal is allowed to do in this specific context.
The surface

Once events exist as first-class entities, the platform can expose a tiny API surface that unlocks an ecosystem.

GET /events History

Search over the platform's declared past. Turns debugging into retrieval. Turns investigations into queries.

GET /events/{id}/why Explain

Returns a human-readable explanation of the event's decision, using only evidence the requester is allowed to see.

GET /decisions Current state

What is the latest decision state for this target? The clean separation between history and current truth.

The resolver

A single source of truth for permission predicates. Every surface uses the same resolver. The platform stops being a collection of permission implementations and becomes one permission system.

The rule

Traverse what was declared before you generate from what was inferred.

Start from tables, not PDFs. Start from event IDs, not screenshots. Start from a permission resolver, not a dozen permission copies. Then, and only then, use a model to fill the genuinely missing parts.

If you ship declared events as a platform contract, you get an irreversible advantage: you can explain yourself. You can audit yourself. You can let others build on you without rebuilding you. And when AI asks "what happened," you can answer with receipts.