feat(objectos): implement ObjectOS system runtime object definitions

OBJECTOS_IMPLEMENTATION.md

@@ -0,0 +1,178 @@
+# 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)
+- [ ] Update `packages/metadata` service to support projection
+- [ ] Implement dual-table sync logic
+- [ ] Register system objects in runtime bootstrap
+
+### 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
+
+```typescript
+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.

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

@@ -0,0 +1,167 @@
+---
+title: Environment Package
+description: Environment Package protocol schemas
+---
+
+{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}
+
+Environment Package Installation Protocol
+
+Models `sys_package_installation` — the pairing between an environment and a
+
+specific, immutable package version snapshot (`sys_package_version`).
+
+Key invariants (per ADR-0003):
+
+- One active version per package per environment at any time.
+
+- **Upgrade** = atomic `UPDATE package_version_id` to a newer version UUID.
+
+- **Rollback** = atomic `UPDATE package_version_id` to an older version UUID.
+
+- The `upgradeHistory` field is removed; history is tracked via the
+
+sequence of `package_version_id` changes on this row (and an optional
+
+`sys_package_installation_history` audit table).
+
+- Only `status = 'published'` versions may be installed in production
+
+environments (draft/pre-release allowed in dev/sandbox with `allowDraft`).
+
+Stored in the **Control Plane DB** (not in environment DBs).
+
+See `docs/adr/0003-package-as-first-class-citizen.md` for the full rationale.
+
+<Callout type="info">
+**Source:** `packages/spec/src/cloud/environment-package.zod.ts`
+</Callout>
+
+## TypeScript Usage
+
+```typescript
+import { EnvPackageStatus, EnvPackageStatusEnum, EnvironmentPackageInstallation, InstallPackageToEnvRequest, ListEnvPackagesResponse, RollbackEnvPackageRequest, UpgradeEnvPackageRequest } from '@objectstack/spec/cloud';
+import type { EnvPackageStatus, EnvPackageStatusEnum, EnvironmentPackageInstallation, InstallPackageToEnvRequest, ListEnvPackagesResponse, RollbackEnvPackageRequest, UpgradeEnvPackageRequest } from '@objectstack/spec/cloud';
+
+// Validate data
+const result = EnvPackageStatus.parse(data);
+```
+
+---
+
+## EnvPackageStatus
+
+Package installation status within an environment
+
+### Allowed Values
+
+* `installed`
+* `installing`
+* `upgrading`
+* `disabled`
+* `error`
+
+
+---
+
+## EnvPackageStatusEnum
+
+Package installation status within an environment
+
+### Allowed Values
+
+* `installed`
+* `installing`
+* `upgrading`
+* `disabled`
+* `error`
+
+
+---
+
+## EnvironmentPackageInstallation
+
+Package installation record in an environment (sys_package_installation)
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **id** | `string` | ✅ | Unique installation record ID |
+| **environmentId** | `string` | ✅ | Environment this installation belongs to |
+| **packageVersionId** | `string` | ✅ | UUID of the installed sys_package_version row |
+| **packageId** | `string` | ✅ | UUID of the parent sys_package row (denormalized for constraint enforcement) |
+| **status** | `Enum<'installed' \| 'installing' \| 'upgrading' \| 'disabled' \| 'error'>` | ✅ | Package installation status within an environment |
+| **enabled** | `boolean` | ✅ | Whether the package metadata is loaded |
+| **settings** | `Record<string, any>` | optional | Per-installation configuration settings |
+| **installedAt** | `string` | ✅ | Installation timestamp (ISO-8601) |
+| **installedBy** | `string` | optional | User ID of the installer |
+| **updatedAt** | `string` | optional | Last update timestamp (ISO-8601) |
+| **errorMessage** | `string` | optional | Error message when status is error |
+
+
+---
+
+## InstallPackageToEnvRequest
+
+Install a package version into a specific environment
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **packageVersionId** | `string` | optional | Exact package version UUID to install (preferred) |
+| **packageManifestId** | `string` | optional | Package manifest ID (reverse-domain, e.g. com.acme.crm) — resolved to version UUID |
+| **version** | `string` | optional | Version string (defaults to latest published) |
+| **allowDraft** | `boolean` | ✅ | Allow installing a draft version (dev/sandbox envs only) |
+| **settings** | `Record<string, any>` | optional | Installation-time configuration settings |
+| **enableOnInstall** | `boolean` | ✅ | Activate the package immediately after install |
+| **installedBy** | `string` | optional | User ID of the installer |
+
+
+---
+
+## ListEnvPackagesResponse
+
+List of packages installed in an environment
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **packages** | `Object[]` | ✅ | Packages installed in this environment |
+| **total** | `number` | ✅ | Total count |
+
+
+---
+
+## RollbackEnvPackageRequest
+
+Roll back a package installation to a specific older version
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **targetPackageVersionId** | `string` | ✅ | Package version UUID to roll back to |
+| **rolledBackBy** | `string` | optional | User ID performing the rollback |
+
+
+---
+
+## UpgradeEnvPackageRequest
+
+Upgrade a package installation to a newer version
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **targetPackageVersionId** | `string` | optional | Target package version UUID (preferred) |
+| **targetVersion** | `string` | optional | Target version string (defaults to latest published) |
+| **allowDraft** | `boolean` | ✅ | Allow upgrading to a draft version |
+| **upgradedBy** | `string` | optional | User ID performing the upgrade |
+
+
+---
+