llms.txt

# @objectstack/spec Context for AI Agents

> **SYSTEM NOTE**: This file provides a high-level summary of the ObjectStack Protocol to help LLMs understand the codebase structure and intent.
> **Version**: 3.0.0

## 1. Architecture Overview (The "Three-Layer Model")

ObjectStack is a metadata-driven "Post-SaaS Operating System".
It is divided into three layers, reflected in the import paths:

### Layer 1: ObjectQL (`@objectstack/spec/data`)
**The Business Kernel**. Defines "What Data Exists".
- **`ObjectSchema`**: Defines database tables (postgres/mongo agnostic).
- **`FieldSchema`**: Defines columns with 46+ types (`text`, `number`, `lookup`, `formula`, `vector`, etc.).
- **`QuerySchema`**: A JSON-based AST for querying data (replaces SQL).
- **`IDataDriver`**: The authoritative contract for database adapters (SQL, NoSQL, Memory).
  Exported from `@objectstack/spec/contracts` — see §6.
- **`CubeSchema`**: OLAP cubes, measures, and dimensions.

### Layer 2: ObjectOS (`@objectstack/spec/system` & `@objectstack/spec/api`)
**The Runtime Kernel**. Defines "How System Operates".
- **`ManifestSchema`**: `objectstack.config.ts` configuration.
- **`OrganizationSchema`**: Organizations, members, positions, SCIM provisioning.
- **`EventSchema`**: System bus, DLQ, and Webhooks (6 sub-modules).
- **`ApiEndpointSchema`**: API Gateway configuration.
- **`PluginSchema`**: Module lifecycle, security, registry, loading.

### Layer 3: ObjectUI (`@objectstack/spec/ui`)
**The Presentation Layer**. Defines "How Users Interact".
- **`AppSchema`**: Navigation menus and branding.
- **`ViewSchema`**: Layouts for data (Grid, Kanban, Calendar, Gantt).
- **`ActionSchema`**: Buttons and triggers.
- **`DashboardSchema`**: Widget composition.

### Layer 4: ObjectAI (`@objectstack/spec/ai`)
**The Intelligence Layer**. Defines AI Agents and Pipelines.
- **`AgentSchema`**: Autonomous actors with tools and permissions.
- **`KnowledgeSourceSchema`**: Retrieval sources backing RAG grounding.
- **`ModelRegistrySchema`**: LLM configuration and routing.
- **`MCPServerRefSchema`**: Model Context Protocol integration.

---

## 2. Coding Patterns (Zod First)

All definitions are **Zod Schemas** with runtime validation.
- **Configuration Keys**: `camelCase` (e.g., `maxLength`, `referenceFilters`).
- **Data Values**: `snake_case` (e.g., `object: 'project_task'`, `type: 'lookup'`).
- **All schemas have `.describe()` annotations** (7,095+ total).
- **TypeScript types derived via `z.infer<typeof Schema>`**.

### Example: Defining an Object
```typescript
import { ObjectSchema } from '@objectstack/spec/data';

const taskObject = {
  name: 'project_task',  // snake_case table name
  label: 'Project Task',
  fields: {
    status: { type: 'select', options: ['todo', 'done'] },
    priority: { type: 'number', defaultValue: 0 }
  }
};
```

### Example: Building a Query
```typescript
import { QuerySchema } from '@objectstack/spec/data';

const query = {
  object: 'project_task',
  filters: [['status', '=', 'todo'], 'and', ['priority', '>', 1]],
  sort: [{ field: 'created_at', order: 'desc' }],
  top: 10
};
```

---

## 3. Schema Inventory by Domain (207 schemas)

Counted as `*.zod.ts` modules under `packages/spec/src/<domain>/` — the sources
that ship in this tarball (`files` includes `src/**/*.zod.ts`), so every number
here is verifiable from the installed package.

| Domain | Count | Key Schemas |
|--------|-------|-------------|
| system | 36 | Auth, Cache, Compliance, Encryption, HTTP Server, License, Logging, Metrics |
| kernel | 31 | Plugin, Manifest, Events (6 sub-modules), Feature, Context, Package Registry |
| data | 30 | Object, Field, Query, Filter, Driver (SQL/NoSQL/Memory/Mongo/Postgres), Cube |
| api | 30 | Endpoint, REST Server, Discovery, OData, Batch, WebSocket, Response Envelope, Package Lifecycle |
| ui | 18 | View, App, Action, Dashboard, Page, Chart, Component, Animation |
| automation | 13 | Flow, Approval, BPMN Interop, Control Flow, State Machine, Webhook |
| shared | 13 | Enums, HTTP, Identifiers, Mapping, Metadata Types, Connector Auth, Retry Policy |
| ai | 11 | Agent, Conversation, Knowledge Source/Document, Model Registry, MCP, Skill, Tool |
| cloud | 11 | Marketplace, Developer Portal, App Store, Environment, Package, Tenant |
| identity | 5 | Identity, Organization, Position, SCIM, Eval User |
| security | 4 | Permission, RLS, Sharing, Explain |
| studio | 3 | Flow Builder, Object Designer, Studio Plugin |
| integration | 1 | Connector |
| qa | 1 | Testing |

---

## 4. Key Exports by Namespace

### `import * as Data from '@objectstack/spec/data'`
- `ObjectSchema`, `FieldSchema`: Logic & Storage definition.
- `QuerySchema`, `FilterArraySchema`: Data retrieval AST.
- `DatasourceSchema`, `DriverInterfaceSchema`: Database connectivity.
- `CubeSchema`: OLAP cubes and metrics.

### `import * as UI from '@objectstack/spec/ui'`
- `ViewSchema`: `type: 'grid' | 'kanban' | 'calendar'`.
- `FormViewSchema`: Form layout and sections.
- `DashboardSchema`: Widget composition.
- `AppSchema`, `ActionSchema`: Navigation and triggers.

### `import * as Kernel from '@objectstack/spec/kernel'`
- `PluginSchema`, `ManifestSchema`: Module lifecycle and configuration.
- `EventSchema`: Pub/Sub definitions.
- `KernelSecurityPolicySchema`: Plugin security rules.

### `import * as AI from '@objectstack/spec/ai'`
- `AgentSchema`: AI agent configuration.
- `KnowledgeSourceSchema`, `KnowledgeDocumentSchema`: Retrieval sources.
- `ModelRegistrySchema`: LLM routing.

### `import * as API from '@objectstack/spec/api'`
- `ApiEndpointSchema`: REST endpoints.
- `ResponseEnvelopeConfigSchema`, `ApiErrorSchema`: Request/Response envelopes.
- `DiscoverySchema`: Service discovery.

---

## 5. Implementing the Protocol (Engine Devs)

### Strict Type Compliance
Use `z.infer` to derive types directly from the protocol. Do not manually re-declare interfaces.

```typescript
import { DriverInterfaceSchema } from '@objectstack/spec/data';
import type { IDataDriver } from '@objectstack/spec/contracts';

export class PostgresDriver implements IDataDriver {
  name = 'postgres';
  async find(object: string, query: z.infer<typeof QuerySchema>) { ... }
}
```

### Runtime Validation
The engine **MUST** validate inputs against the Zod schemas before processing.

```typescript
import { ObjectSchema } from '@objectstack/spec/data';

function registerObject(rawConfig: unknown) {
  const config = ObjectSchema.parse(rawConfig);
  // ... proceed
}
```

---

## 6. Service Contracts (`@objectstack/spec/contracts`)

| Contract | Methods |
|----------|---------|
| `IMetadataService` | register, get, list, delete, query, bulk ops, watch, import/export |
| `IAnalyticsService` | query, aggregate, timeSeries |
| `IAuthService` | authenticate, authorize, validateToken |
| `IAutomationService` | executeFlow, triggerWorkflow |

---

## 7. Package Ecosystem (68 packages)

The workspace publishes 68 packages under the `@objectstack` scope. The table
below is a curated entry-point list, not the full set — drivers, connectors,
triggers, plugins and kernel-managed services each form their own family.

| Package | Description |
|---------|-------------|
| `@objectstack/spec` | Protocol schemas (this package) |
| `@objectstack/core` | Runtime core (plugin loader, security, sandbox) |
| `@objectstack/runtime` | HTTP dispatcher, middleware |
| `@objectstack/objectql` | Query engine |
| `@objectstack/rest` | REST API server and route manager |
| `@objectstack/metadata` | Metadata management service |
| `@objectstack/client` | JavaScript client SDK |
| `@objectstack/client-react` | React hooks for client |
| `@objectstack/cli` | Command-line interface |
| `@objectstack/hono` | Hono adapter |
| `@objectstack/driver-memory` | In-memory database driver |
| `@objectstack/driver-sql` | SQL database driver |
| `@objectstack/types` | Shared TypeScript utilities |

---

## 8. JSON Schema & OpenAPI

- **1,470+ JSON Schemas** auto-generated from Zod (with `$id` URLs)
- **Bundled schema**: `json-schema/objectstack.json` for IDE autocomplete
- **OpenAPI 3.1**: Auto-generated from REST API protocol (`json-schema/openapi.json`)
- **Schema versioning**: `x-spec-version` field in all generated schemas

---

## 9. Upgrading Across Spec Versions

When a dependency bump makes `ObjectSchema.create()` (or `objectstack validate`)
reject a key that used to work:

1. **Read the error first** — retired keys carry a tombstone message naming the
   replacement key and the version/decision that removed it. The fix is in the
   error text; no external lookup needed.
2. **`CHANGELOG.md` ships inside this package** (`node_modules/@objectstack/spec/CHANGELOG.md`).
   It is version-ordered and every breaking entry includes its migration notes.
   Grep it for the rejected key to see the full context of the change.
3. Do NOT re-add rejected keys or downgrade to make errors disappear — the keys
   were removed deliberately (enforce-or-remove, ADR-0049); renaming/migrating
   per the tombstone is always a small, mechanical edit.