OBJECTOS_IMPLEMENTATION.md

ObjectOS Implementation Summary

Overview

Successfully implemented the ObjectOS layer - a new @objectstack/objectos package containing system runtime object definitions that represent metadata as queryable data.

Architecture Decision

Based on architectural discussions, we established:

1. Location: packages/objectos (NOT packages/plugins/plugin-system)

   • Rationale: System objects are core infrastructure, not optional plugins
   • ObjectOS represents the OS-level primitives of the platform

2. Dual-Table Pattern: Keep BOTH systems (do NOT deprecate sys_metadata)

   • sys_metadata: Source of truth for package management, version control, deployment
   • Type-specific tables (sys_object, sys_view, etc.): Queryable data for UI/reporting

Package Structure

packages/objectos/
├── src/
│   ├── objects/
│   │   ├── sys-metadata.object.ts     # Generic metadata envelope
│   │   ├── sys-object.object.ts       # Object definitions
│   │   ├── sys-view.object.ts         # View definitions
│   │   ├── sys-agent.object.ts        # AI Agent definitions
│   │   ├── sys-tool.object.ts         # AI Tool definitions
│   │   ├── sys-flow.object.ts         # Flow definitions
│   │   └── index.ts
│   ├── index.ts                        # Package entry point
│   └── registry.ts                     # System object registry
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── README.md

System Objects Implemented

1. sys_metadata (Generic Envelope)

• Purpose: Source of truth for package management
• Features: Version control, checksums, package ownership, deployment tracking
• Fields: 20+ fields including version, checksum, package_id, managed_by, scope

2. sys_object (Queryable Object Definitions)

• Purpose: Browse/filter/search object definitions in Studio
• Features: Denormalized data, complex fields as JSON
• Fields: 30+ fields including fields_json, capabilities_json, field_count

3. sys_view (Queryable View Definitions)

• Purpose: Manage view metadata through Object Protocol
• Features: View type filtering, object references
• Fields: columns_json, filters_json, sort_json, config_json

4. sys_agent (AI Agent Definitions)

• Purpose: AI agent configuration as data
• Features: Model config, tools/skills management
• Fields: model, temperature, system_prompt, tools_json, skills_json

5. sys_tool (AI Tool Definitions)

• Purpose: AI tool registry as queryable data
• Features: Parameter schemas, handler code
• Fields: parameters_json, handler_code

6. sys_flow (Automation Flow Definitions)

• Purpose: Flow metadata management
• Features: Flow types, trigger configuration
• Fields: flow_type, nodes_json, edges_json, trigger_type

Key Features

1. Metadata as Data

   • All metadata types are queryable using Object Protocol
   • Same CRUD operations as business data
   • Consistent API: /api/v1/data/sys_object, /api/v1/data/sys_view

2. Dual-Table Architecture

   Package Loader
        ↓
   sys_metadata (source of truth)
        ↓ (projection)
   sys_object, sys_view, etc. (queryable)
        ↓
   Studio UI (auto-generated)
   

3. Version Management

   • sys_metadata tracks all versions
   • sys_metadata_history table for history
   • Checksum-based change detection
   • Package upgrade/downgrade support

4. Auto-Generated UI

   • Studio uses Object Protocol
   • No custom UI code per metadata type
   • Leverage grid/form/kanban views

Industry Alignment

• Salesforce: CustomObject, CustomField (queryable metadata)
• ServiceNow: sys_db_object, sys_dictionary (table-based metadata)
• Kubernetes: CRDs as structured resources

Next Steps

Phase 1: Integration (Immediate) ✅ COMPLETED

• Update packages/metadata service to support projection
• Implement dual-table sync logic
• Register system objects in runtime bootstrap

Implementation Details:

• Created MetadataProjector service in packages/metadata/src/projection/
• Integrated projection into DatabaseLoader.save() and DatabaseLoader.delete()
• Added projection functions for each metadata type: object, view, agent, tool, flow
• Updated MetadataPlugin to register all system objects from @objectstack/objectos
• Projection is enabled by default, can be disabled via enableProjection: false option

Phase 2: Studio Integration (Next)

• Update Studio to query type-specific tables
• Use /api/v1/data/sys_object for browsing
• Auto-generate metadata forms

Phase 3: Testing & Documentation (Later)

• Add comprehensive test coverage
• Update documentation
• Create migration guides

Usage Example

import { SystemObjects } from '@objectstack/objectos';

// Register all system objects during bootstrap
for (const [name, definition] of Object.entries(SystemObjects)) {
  await kernel.metadata.register('object', name, definition, {
    scope: 'system',
    isSystem: true,
    managedBy: 'platform',
  });
}

// Query metadata using Object Protocol
const objects = await client.data.find('sys_object', {
  filter: { namespace: 'crm' },
  sort: 'name',
});

// Studio auto-generates UI
<GridView object="sys_object" />
<FormView object="sys_object" recordId="account" />

Benefits

1. ✅ Unified Protocol: One protocol for both data and metadata
2. ✅ Auto-Generated UI: Studio reuses existing components
3. ✅ Better DX: Consistent API for all entity types
4. ✅ Version Control: Full history via sys_metadata_history
5. ✅ Package Management: Track ownership and deployments
6. ✅ Industry Standard: Follows Salesforce/ServiceNow patterns

Files Created

• /home/runner/work/framework/framework/packages/objectos/package.json
• /home/runner/work/framework/framework/packages/objectos/tsconfig.json
• /home/runner/work/framework/framework/packages/objectos/tsup.config.ts
• /home/runner/work/framework/framework/packages/objectos/README.md
• /home/runner/work/framework/framework/packages/objectos/src/index.ts
• /home/runner/work/framework/framework/packages/objectos/src/registry.ts
• /home/runner/work/framework/framework/packages/objectos/src/objects/index.ts
• /home/runner/work/framework/framework/packages/objectos/src/objects/sys-metadata.object.ts
• /home/runner/work/framework/framework/packages/objectos/src/objects/sys-object.object.ts
• /home/runner/work/framework/framework/packages/objectos/src/objects/sys-view.object.ts
• /home/runner/work/framework/framework/packages/objectos/src/objects/sys-agent.object.ts
• /home/runner/work/framework/framework/packages/objectos/src/objects/sys-tool.object.ts
• /home/runner/work/framework/framework/packages/objectos/src/objects/sys-flow.object.ts

Conclusion

The ObjectOS package establishes a clean architectural foundation for treating metadata as queryable data. This enables auto-generated Studio UI, unified APIs, and follows industry best practices from Salesforce, ServiceNow, and Kubernetes.

The dual-table architecture preserves the benefits of sys_metadata for package management while adding queryability through type-specific tables.