Skip to content

Commit 5afaf72

Browse files
hotlonghotlong
authored
Merge pull request #1192 from objectstack-ai/claude/refactor-metadata-types-into-objects
feat(objectos): implement ObjectOS system runtime object definitions
2 parents 33d1842 + 364bb64 commit 5afaf72

32 files changed

Lines changed: 2434 additions & 3 deletions

‎OBJECTOS_IMPLEMENTATION.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# ObjectOS Implementation Summary
2+
3+
## Overview
4+
5+
Successfully implemented the ObjectOS layer - a new `@objectstack/objectos` package containing system runtime object definitions that represent metadata as queryable data.
6+
7+
## Architecture Decision
8+
9+
Based on architectural discussions, we established:
10+
11+
1. **Location**: `packages/objectos` (NOT `packages/plugins/plugin-system`)
12+
- Rationale: System objects are core infrastructure, not optional plugins
13+
- ObjectOS represents the OS-level primitives of the platform
14+
15+
2. **Dual-Table Pattern**: Keep BOTH systems (do NOT deprecate `sys_metadata`)
16+
- `sys_metadata`: Source of truth for package management, version control, deployment
17+
- Type-specific tables (`sys_object`, `sys_view`, etc.): Queryable data for UI/reporting
18+
19+
## Package Structure
20+
21+
```
22+
packages/objectos/
23+
├── src/
24+
│ ├── objects/
25+
│ │ ├── sys-metadata.object.ts # Generic metadata envelope
26+
│ │ ├── sys-object.object.ts # Object definitions
27+
│ │ ├── sys-view.object.ts # View definitions
28+
│ │ ├── sys-agent.object.ts # AI Agent definitions
29+
│ │ ├── sys-tool.object.ts # AI Tool definitions
30+
│ │ ├── sys-flow.object.ts # Flow definitions
31+
│ │ └── index.ts
32+
│ ├── index.ts # Package entry point
33+
│ └── registry.ts # System object registry
34+
├── package.json
35+
├── tsconfig.json
36+
├── tsup.config.ts
37+
└── README.md
38+
```
39+
40+
## System Objects Implemented
41+
42+
### 1. sys_metadata (Generic Envelope)
43+
- **Purpose**: Source of truth for package management
44+
- **Features**: Version control, checksums, package ownership, deployment tracking
45+
- **Fields**: 20+ fields including version, checksum, package_id, managed_by, scope
46+
47+
### 2. sys_object (Queryable Object Definitions)
48+
- **Purpose**: Browse/filter/search object definitions in Studio
49+
- **Features**: Denormalized data, complex fields as JSON
50+
- **Fields**: 30+ fields including fields_json, capabilities_json, field_count
51+
52+
### 3. sys_view (Queryable View Definitions)
53+
- **Purpose**: Manage view metadata through Object Protocol
54+
- **Features**: View type filtering, object references
55+
- **Fields**: columns_json, filters_json, sort_json, config_json
56+
57+
### 4. sys_agent (AI Agent Definitions)
58+
- **Purpose**: AI agent configuration as data
59+
- **Features**: Model config, tools/skills management
60+
- **Fields**: model, temperature, system_prompt, tools_json, skills_json
61+
62+
### 5. sys_tool (AI Tool Definitions)
63+
- **Purpose**: AI tool registry as queryable data
64+
- **Features**: Parameter schemas, handler code
65+
- **Fields**: parameters_json, handler_code
66+
67+
### 6. sys_flow (Automation Flow Definitions)
68+
- **Purpose**: Flow metadata management
69+
- **Features**: Flow types, trigger configuration
70+
- **Fields**: flow_type, nodes_json, edges_json, trigger_type
71+
72+
## Key Features
73+
74+
1. **Metadata as Data**
75+
- All metadata types are queryable using Object Protocol
76+
- Same CRUD operations as business data
77+
- Consistent API: `/api/v1/data/sys_object`, `/api/v1/data/sys_view`
78+
79+
2. **Dual-Table Architecture**
80+
```
81+
Package Loader
82+
↓
83+
sys_metadata (source of truth)
84+
↓ (projection)
85+
sys_object, sys_view, etc. (queryable)
86+
↓
87+
Studio UI (auto-generated)
88+
```
89+
90+
3. **Version Management**
91+
- `sys_metadata` tracks all versions
92+
- `sys_metadata_history` table for history
93+
- Checksum-based change detection
94+
- Package upgrade/downgrade support
95+
96+
4. **Auto-Generated UI**
97+
- Studio uses Object Protocol
98+
- No custom UI code per metadata type
99+
- Leverage grid/form/kanban views
100+
101+
## Industry Alignment
102+
103+
- **Salesforce**: CustomObject, CustomField (queryable metadata)
104+
- **ServiceNow**: sys_db_object, sys_dictionary (table-based metadata)
105+
- **Kubernetes**: CRDs as structured resources
106+
107+
## Next Steps
108+
109+
### Phase 1: Integration (Immediate)
110+
- [ ] Update `packages/metadata` service to support projection
111+
- [ ] Implement dual-table sync logic
112+
- [ ] Register system objects in runtime bootstrap
113+
114+
### Phase 2: Studio Integration (Next)
115+
- [ ] Update Studio to query type-specific tables
116+
- [ ] Use `/api/v1/data/sys_object` for browsing
117+
- [ ] Auto-generate metadata forms
118+
119+
### Phase 3: Testing & Documentation (Later)
120+
- [ ] Add comprehensive test coverage
121+
- [ ] Update documentation
122+
- [ ] Create migration guides
123+
124+
## Usage Example
125+
126+
```typescript
127+
import { SystemObjects } from '@objectstack/objectos';
128+
129+
// Register all system objects during bootstrap
130+
for (const [name, definition] of Object.entries(SystemObjects)) {
131+
await kernel.metadata.register('object', name, definition, {
132+
scope: 'system',
133+
isSystem: true,
134+
managedBy: 'platform',
135+
});
136+
}
137+
138+
// Query metadata using Object Protocol
139+
const objects = await client.data.find('sys_object', {
140+
filter: { namespace: 'crm' },
141+
sort: 'name',
142+
});
143+
144+
// Studio auto-generates UI
145+
<GridView object="sys_object" />
146+
<FormView object="sys_object" recordId="account" />
147+
```
148+
149+
## Benefits
150+
151+
1. ✅ **Unified Protocol**: One protocol for both data and metadata
152+
2. ✅ **Auto-Generated UI**: Studio reuses existing components
153+
3. ✅ **Better DX**: Consistent API for all entity types
154+
4. ✅ **Version Control**: Full history via sys_metadata_history
155+
5. ✅ **Package Management**: Track ownership and deployments
156+
6. ✅ **Industry Standard**: Follows Salesforce/ServiceNow patterns
157+
158+
## Files Created
159+
160+
- `/home/runner/work/framework/framework/packages/objectos/package.json`
161+
- `/home/runner/work/framework/framework/packages/objectos/tsconfig.json`
162+
- `/home/runner/work/framework/framework/packages/objectos/tsup.config.ts`
163+
- `/home/runner/work/framework/framework/packages/objectos/README.md`
164+
- `/home/runner/work/framework/framework/packages/objectos/src/index.ts`
165+
- `/home/runner/work/framework/framework/packages/objectos/src/registry.ts`
166+
- `/home/runner/work/framework/framework/packages/objectos/src/objects/index.ts`
167+
- `/home/runner/work/framework/framework/packages/objectos/src/objects/sys-metadata.object.ts`
168+
- `/home/runner/work/framework/framework/packages/objectos/src/objects/sys-object.object.ts`
169+
- `/home/runner/work/framework/framework/packages/objectos/src/objects/sys-view.object.ts`
170+
- `/home/runner/work/framework/framework/packages/objectos/src/objects/sys-agent.object.ts`
171+
- `/home/runner/work/framework/framework/packages/objectos/src/objects/sys-tool.object.ts`
172+
- `/home/runner/work/framework/framework/packages/objectos/src/objects/sys-flow.object.ts`
173+
174+
## Conclusion
175+
176+
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.
177+
178+
The dual-table architecture preserves the benefits of `sys_metadata` for package management while adding queryability through type-specific tables.

‎content/docs/references/cloud/environment-package.mdx‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
title: Environment Package
3+
description: Environment Package protocol schemas
4+
---
5+
6+
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}
7+
8+
Environment Package Installation Protocol
9+
10+
Models `sys_package_installation` — the pairing between an environment and a
11+
12+
specific, immutable package version snapshot (`sys_package_version`).
13+
14+
Key invariants (per ADR-0003):
15+
16+
- One active version per package per environment at any time.
17+
18+
- **Upgrade** = atomic `UPDATE package_version_id` to a newer version UUID.
19+
20+
- **Rollback** = atomic `UPDATE package_version_id` to an older version UUID.
21+
22+
- The `upgradeHistory` field is removed; history is tracked via the
23+
24+
sequence of `package_version_id` changes on this row (and an optional
25+
26+
`sys_package_installation_history` audit table).
27+
28+
- Only `status = 'published'` versions may be installed in production
29+
30+
environments (draft/pre-release allowed in dev/sandbox with `allowDraft`).
31+
32+
Stored in the **Control Plane DB** (not in environment DBs).
33+
34+
See `docs/adr/0003-package-as-first-class-citizen.md` for the full rationale.
35+
36+
<Callout type="info">
37+
**Source:** `packages/spec/src/cloud/environment-package.zod.ts`
38+
</Callout>
39+
40+
## TypeScript Usage
41+
42+
```typescript
43+
import { EnvPackageStatus, EnvPackageStatusEnum, EnvironmentPackageInstallation, InstallPackageToEnvRequest, ListEnvPackagesResponse, RollbackEnvPackageRequest, UpgradeEnvPackageRequest } from '@objectstack/spec/cloud';
44+
import type { EnvPackageStatus, EnvPackageStatusEnum, EnvironmentPackageInstallation, InstallPackageToEnvRequest, ListEnvPackagesResponse, RollbackEnvPackageRequest, UpgradeEnvPackageRequest } from '@objectstack/spec/cloud';
45+
46+
// Validate data
47+
const result = EnvPackageStatus.parse(data);
48+
```
49+
50+
---
51+
52+
## EnvPackageStatus
53+
54+
Package installation status within an environment
55+
56+
### Allowed Values
57+
58+
* `installed`
59+
* `installing`
60+
* `upgrading`
61+
* `disabled`
62+
* `error`
63+
64+
65+
---
66+
67+
## EnvPackageStatusEnum
68+
69+
Package installation status within an environment
70+
71+
### Allowed Values
72+
73+
* `installed`
74+
* `installing`
75+
* `upgrading`
76+
* `disabled`
77+
* `error`
78+
79+
80+
---
81+
82+
## EnvironmentPackageInstallation
83+
84+
Package installation record in an environment (sys_package_installation)
85+
86+
### Properties
87+
88+
| Property | Type | Required | Description |
89+
| :--- | :--- | :--- | :--- |
90+
| **id** | `string` | ✅ | Unique installation record ID |
91+
| **environmentId** | `string` | ✅ | Environment this installation belongs to |
92+
| **packageVersionId** | `string` | ✅ | UUID of the installed sys_package_version row |
93+
| **packageId** | `string` | ✅ | UUID of the parent sys_package row (denormalized for constraint enforcement) |
94+
| **status** | `Enum<'installed' \| 'installing' \| 'upgrading' \| 'disabled' \| 'error'>` | ✅ | Package installation status within an environment |
95+
| **enabled** | `boolean` | ✅ | Whether the package metadata is loaded |
96+
| **settings** | `Record<string, any>` | optional | Per-installation configuration settings |
97+
| **installedAt** | `string` | ✅ | Installation timestamp (ISO-8601) |
98+
| **installedBy** | `string` | optional | User ID of the installer |
99+
| **updatedAt** | `string` | optional | Last update timestamp (ISO-8601) |
100+
| **errorMessage** | `string` | optional | Error message when status is error |
101+
102+
103+
---
104+
105+
## InstallPackageToEnvRequest
106+
107+
Install a package version into a specific environment
108+
109+
### Properties
110+
111+
| Property | Type | Required | Description |
112+
| :--- | :--- | :--- | :--- |
113+
| **packageVersionId** | `string` | optional | Exact package version UUID to install (preferred) |
114+
| **packageManifestId** | `string` | optional | Package manifest ID (reverse-domain, e.g. com.acme.crm) — resolved to version UUID |
115+
| **version** | `string` | optional | Version string (defaults to latest published) |
116+
| **allowDraft** | `boolean` | ✅ | Allow installing a draft version (dev/sandbox envs only) |
117+
| **settings** | `Record<string, any>` | optional | Installation-time configuration settings |
118+
| **enableOnInstall** | `boolean` | ✅ | Activate the package immediately after install |
119+
| **installedBy** | `string` | optional | User ID of the installer |
120+
121+
122+
---
123+
124+
## ListEnvPackagesResponse
125+
126+
List of packages installed in an environment
127+
128+
### Properties
129+
130+
| Property | Type | Required | Description |
131+
| :--- | :--- | :--- | :--- |
132+
| **packages** | `Object[]` | ✅ | Packages installed in this environment |
133+
| **total** | `number` | ✅ | Total count |
134+
135+
136+
---
137+
138+
## RollbackEnvPackageRequest
139+
140+
Roll back a package installation to a specific older version
141+
142+
### Properties
143+
144+
| Property | Type | Required | Description |
145+
| :--- | :--- | :--- | :--- |
146+
| **targetPackageVersionId** | `string` | ✅ | Package version UUID to roll back to |
147+
| **rolledBackBy** | `string` | optional | User ID performing the rollback |
148+
149+
150+
---
151+
152+
## UpgradeEnvPackageRequest
153+
154+
Upgrade a package installation to a newer version
155+
156+
### Properties
157+
158+
| Property | Type | Required | Description |
159+
| :--- | :--- | :--- | :--- |
160+
| **targetPackageVersionId** | `string` | optional | Target package version UUID (preferred) |
161+
| **targetVersion** | `string` | optional | Target version string (defaults to latest published) |
162+
| **allowDraft** | `boolean` | ✅ | Allow upgrading to a draft version |
163+
| **upgradedBy** | `string` | optional | User ID performing the upgrade |
164+
165+
166+
---
167+

0 commit comments

Comments
 (0)