Specifications Overview

"We shape our tools and thereafter our tools shape us." — Marshall McLuhan

Welcome to the Specifications section (The "Bible") of ObjectStack.

Unlike the Guides (which tell you how to use the SDK) or the Concepts (which explain the philosophy), this section defines the Strict Contracts of the ecosystem. It details the wire formats, schema structures, and deterministic behaviors that every ObjectStack implementation must adhere to.

If you are building a new Database Driver, a custom UI Renderer, or an AI Agent that generates software, this is your reference manual.

Core Philosophy: Intent over Implementation

The singular axiom driving these specifications is Intent over Implementation.

In traditional software engineering, the "Business Intent" is inextricably mixed with "Technical Implementation."

Intent: "Users over 18 can see the 'Wine' category."
Implementation: A Python if statement, a SQL WHERE clause, or a React conditional render.

ObjectStack separates these completely.

The Separation of Concerns

Layer	Responsibility	Format	Example
Intent (The Spec)	Defines WHAT the system is.	JSON / YAML	`visible_on: "user.age >= 18"`
Engine (The Runtime)	Decides HOW to execute it.	Node.js / Go / Rust	Compiles to SQL or hydrates a React Tree.

By freezing the Intent into a standardized Data Protocol, we achieve:

Portability: The same logic runs on PostgreSQL, SQLite, or MongoDB.
Longevity: The JSON schema you write today will still be valid in 10 years, even if the underlying runtime switches from Node.js to Bun or Rust.
AI-Nativity: It is safer and more accurate for an AI to generate a structured JSON intent than to generate imperative code full of side effects.

The Protocol Stack

These specifications are divided into three pillars, corresponding to the "Trinity" architecture:

1. ObjectQL (The Data Specification)

Focus: Data Modeling, Querying, and Mutation.
Key Specs: Schema Definition, AST Wire Protocol, Transaction Model.
Goal: To make the database layer declarative and interchangeable.

2. ObjectUI (The View Specification)

Focus: Interface Structure, Layout, and Interaction.
Key Specs: Component Schema, View Types, Action Protocol.
Goal: To enable Server-Driven UI where the backend dictates the frontend experience.

3. ObjectOS (The Runtime Specification)

Focus: Identity, Governance, and Orchestration.
Key Specs: Workflow FSM, Permission Injection, Audit Trail.
Goal: To provide a standard operating environment for business logic.

Conformance & Terminology

In this documentation, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119.

Who is this for?

✅ Architect: To understand the capabilities and constraints of the system.
✅ Driver Developer: To implement a new storage backend (e.g., a ClickHouse driver).
✅ Platform Engineer: To integrate ObjectStack into an existing microservices mesh.
❌ Junior Developer: If you just want to build an app, start with the Getting Started guide instead.

Proceed to the first specification: ObjectQL Overview