---
title: Design Principles
description: The unshakable core principles that govern ObjectStack as an AI-native business backend
---

import { Scale, Code2, Database, ScrollText } from 'lucide-react';

# Design Principles

ObjectStack exists to make enterprise application development explicit enough for both humans and AI agents to operate safely: **structured business metadata**.

To maintain a healthy, decoupled, and future-proof ecosystem, we uphold the following core principles. These are not suggestions; they are the constraints that enable our freedom.

<Cards>
  <Card
    icon={<Scale />}
    title="I. Protocol Neutrality"
    description="The Protocol is law. The Implementation is merely an opinion."
  />
  <Card
    icon={<Code2 />}
    title="II. Mechanism over Policy"
    description="Provide the tools to build rules, do not hardcode the rules themselves."
  />
  <Card
    icon={<Database />}
    title="III. Single Source of Truth"
    description="There is no 'Code'. There is only Schema."
  />
  <Card
    icon={<ScrollText />}
    title="IV. Agent-Ready Boundaries"
    description="Agents may act only through typed, permission-aware, auditable surfaces."
  />
</Cards>

---

## Principle I: Protocol Neutrality

**"The Protocol is neutral. The Engine is replaceable."**

ObjectQL must not contain any logic specific to a particular language (e.g., Node.js), database (e.g., PostgreSQL), or runtime (e.g., Browser).

### The Law

- **Spec before Engine:** Any feature must first be defined in the Specification layer (`packages/spec`) before a single line of code is written in the Engine layer. We reject the "implement first, standardize later" approach.
- **Zero Leakage:** Implementation details (like React Hooks usage, or SQL specific syntax) must never leak into the Protocol definition.

### The Benefit

This ensures that an ObjectStack application defined today can theoretically run on:

- A Node.js server with PostgreSQL (Today's Standard)
- A Python server with SQLite (AI/Data Science)
- A Rust WASM module in the browser (Local-First)

---

## Principle II: Mechanism over Policy

**"Give them the physics, not the simulation."**

ObjectStack provides the **Mechanisms** (The "How"):

- *"Here is how you define a validation rule."*
- *"Here is how you define a permission scope."*

ObjectStack never dictates the **Policy** (The "What"):

- *It never says "Passwords must be 8 characters".*
- *It never says "Users must belong to a Department".*

### Separation of Concerns

We cleanly separate the **Definition** from the **Execution**.

| Layer | Responsibility | Example |
| :--- | :--- | :--- |
| **Protocol (Mechanism)** | Defines the capabilities. | `allowRead: string` (A slot for a formula) |
| **App (Policy)** | Defines the business logic. | `allowRead: "$user.role == 'admin'"` |
| **Engine (Execution)** | Enforces the logic. | Compiles formula to SQL `WHERE` clause. |

**Policies are metadata, not code.** Permission rules, validation predicates, sharing conditions, and flow guards are all expressed as analyzable CEL/Zod metadata — the same engine evaluates them for human users, REST callers, and AI agent tools, and every decision is traceable to a versioned artifact.

---

## Principle III: The Single Source of Truth

**"There is no 'Code'. There is only Schema."**

In a traditional application, the "truth" is scattered:

1. Database Schema (`table.sql`)
2. Backend Models (`User.ts`)
3. Frontend Validation (`schema.zod.ts`)
4. API Documentation (`swagger.json`)

In ObjectStack, **The Object Protocol is the only truth.**

- The Database is a *derivative* of the Protocol.
- The UI is a *projection* of the Protocol.
- The API is a *consequence* of the Protocol.
- The Agent tool surface is a *bounded capability set* derived from the Protocol.

If you change the Protocol, the entire system (DB, API, UI, tools, and audit context) must adapt automatically.

---

## Principle IV: Agent-Ready Boundaries

**"Agents are powerful only when their boundaries are explicit."**

AI agents should not bypass the application model by calling raw SQL, scraping UI state, or executing arbitrary glue code. They should act through typed, permission-aware capabilities derived from the same metadata artifact that powers the application.

- **Typed inputs:** Tool schemas derive from object fields, action contracts, and validation rules.
- **Permission-aware execution:** RBAC, RLS, and FLS apply to agent actions exactly as they apply to users.
- **Auditable outcomes:** Every agent action should be traceable to the artifact version, user/org context, tool, input, and result.

### The Hidden Tool Problem

In many AI-enabled apps, the agent sees a set of hand-written tools that drift from the real business system:

```
Database schema -> App code -> UI state -> Custom query -> Hand-written MCP tool
```

Each translation layer can lose validation, authorization, or business meaning.

### The ObjectStack Solution

ObjectStack derives agent capabilities from the protocol itself:

```
Zod metadata -> Environment Artifact -> ObjectStack runtime -> API / UI / MCP tools
```

**Benefits:**

1. **No tool drift:** Generated tools stay aligned with object schemas and permissions.
2. **Safer autonomy:** Agents act inside explicit business boundaries.
3. **Auditability:** Runtime decisions can be traced to versioned metadata.

---

## Summary

These principles guide every design decision in ObjectStack:

| Principle | What it Means |
| :--- | :--- |
| **Protocol Neutrality** | The spec is separate from implementation. ObjectStack can run anywhere. |
| **Mechanism over Policy** | We provide the tools, you define the rules. |
| **Single Source of Truth** | The schema is the application. Everything else derives from it. |
| **Agent-Ready Boundaries** | Agents act through typed, permission-aware, auditable capabilities. |

By adhering to these values, we build software that is **resilient to change**, **safe for automation**, and **explicit enough for AI-native business execution**.

## Next Steps

- [Architecture](/docs/concepts/architecture) - See how these principles shape the system
- [Glossary](/docs/concepts/terminology) - Understand key terms
- [Core Concepts](/docs/core-concepts) - Learn about metadata-driven development
