feat(objectos): implement ObjectOS system runtime object definitions

[Claude]

Summary

Implements the ObjectOS layer - system metadata types as queryable objects following the "Metadata as Data" pattern. Establishes dual-table architecture where sys_metadata remains the source of truth for package management while type-specific tables enable Studio UI auto-generation.

Architecture Decisions

Package Location: packages/objectos (not packages/plugins/plugin-system)

• System objects are core infrastructure, not optional plugins
• ObjectOS represents OS-level primitives

Dual-Table Pattern: Preserves sys_metadata alongside queryable objects

• sys_metadata: Package management, version control, checksums, deployment tracking
• Type-specific tables (sys_object, sys_view, etc.): Queryable via Object Protocol for Studio UI

Implementation

Package Structure

packages/objectos/
├── src/
│   ├── objects/
│   │   ├── sys-metadata.object.ts     # Generic envelope (20+ fields)
│   │   ├── sys-object.object.ts       # Object definitions (30+ fields)
│   │   ├── sys-view.object.ts         # View definitions
│   │   ├── sys-agent.object.ts        # AI agents
│   │   ├── sys-tool.object.ts         # AI tools
│   │   └── sys-flow.object.ts         # Automation flows
│   ├── registry.ts                     # SystemObjects registry
│   └── index.ts

System Objects (6 core definitions)

• sys_metadata: Version control, package ownership, scope management
• sys_object: Queryable object metadata with denormalized fields
• sys_view: View configurations with type filtering
• sys_agent: AI agent definitions with model config
• sys_tool: AI tool registry with parameter schemas
• sys_flow: Automation flows with trigger config

Each object includes:

• Complete field definitions using Field factory API
• Appropriate indexes for performance
• Package management fields (package_id, managed_by)
• Audit trail (created_by, created_at, updated_by, updated_at)
• System capabilities (trackHistory, searchable, apiEnabled)

Usage

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

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

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

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

Benefits

• Unified protocol for data and metadata
• Auto-generated Studio UI (no custom components per metadata type)
• Full version history via sys_metadata_history
• Package-aware metadata management
• Aligns with Salesforce CustomObject, ServiceNow sys_dictionary, Kubernetes CRD patterns

Next Steps

Phase 1: Update metadata service with dual-table projection logic
Phase 2: Studio integration using /api/v1/data/sys_* endpoints
Phase 3: Test coverage and migration guides

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectstack-demo	Ready	Preview, Comment	Apr 20, 2026 11:37am
spec	Ready	Preview, Comment	Apr 20, 2026 11:37am

[Copilot]

Pull request overview

Implements the new ObjectOS runtime layer (@objectstack/objectos) by introducing system metadata types as queryable objects (Metadata-as-Data), alongside related spec/schema and documentation updates.

Changes:

• Added new @objectstack/objectos package with 6 core sys_* object definitions and a registry for bootstrap registration.
• Extended metadata persistence protocol to include tenantId as an alias field.
• Updated metadata/history retrieval ordering and refreshed auto-generated reference docs.

Reviewed changes

Copilot reviewed 31 out of 32 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Adds workspace importer/deps for the new packages/objectos package.
packages/spec/src/system/metadata-persistence.zod.ts	Adds optional tenantId alongside organizationId in MetadataRecordSchema.
packages/objectos/vitest.config.ts	Introduces Vitest configuration for the new package.
packages/objectos/tsup.config.ts	Configures tsup build outputs (CJS/ESM + dts) and subpath entry for objects.
packages/objectos/tsconfig.json	TypeScript config for build output and test exclusion.
packages/objectos/src/registry.ts	Adds SystemObjects registry and helper getters for system object definitions.
packages/objectos/src/objects/sys-metadata.object.ts	Defines sys_metadata object envelope for metadata persistence/versioning.
packages/objectos/src/objects/sys-object.object.ts	Defines sys_object queryable projection for object definitions.
packages/objectos/src/objects/sys-view.object.ts	Defines sys_view queryable projection for view definitions.
packages/objectos/src/objects/sys-agent.object.ts	Defines sys_agent queryable projection for AI agent definitions.
packages/objectos/src/objects/sys-tool.object.ts	Defines sys_tool queryable projection for AI tool definitions.
packages/objectos/src/objects/sys-flow.object.ts	Defines sys_flow queryable projection for automation flow definitions.
packages/objectos/src/objects/index.ts	Re-exports all ObjectOS system object definitions.
packages/objectos/src/index.ts	Package entrypoint exporting objects + registry and documenting ObjectOS layering.
packages/objectos/src/objects/sys-metadata.object.test.ts	Adds minimal test to establish test infrastructure for ObjectOS.
packages/objectos/package.json	Defines package metadata, exports map, scripts, and dependencies.
packages/objectos/README.md	Documents ObjectOS intent, architecture, and usage.
packages/objectos/CI_FIXES.md	Adds CI troubleshooting notes for the new package.
packages/metadata/src/metadata.test.ts	Updates expectation for setDataEngine invocation signature.
packages/metadata/src/loaders/database-loader.ts	Adds secondary sort by version when listing metadata history.
content/docs/references/ui/dashboard.mdx	Updates reference docs with new dashboard properties (columns, gap).
content/docs/references/system/translation.mdx	Updates translation reference docs to include description.
content/docs/references/system/metadata-persistence.mdx	Refreshes metadata persistence reference docs (org/env/tenant fields).
content/docs/references/kernel/manifest.mdx	Updates manifest reference docs to include scope.
content/docs/references/cloud/plugin-security.mdx	Adds new cloud reference doc page for plugin security schema.
content/docs/references/cloud/package.mdx	Adds new cloud reference doc page for package schema.
content/docs/references/cloud/package-version.mdx	Adds new cloud reference doc page for package version schema.
content/docs/references/cloud/environment.mdx	Adds new cloud reference doc page for environment schema.
content/docs/references/cloud/environment-package.mdx	Adds new cloud reference doc page for environment package installation schema.
content/docs/references/cloud/meta.json	Adds new cloud pages to references navigation metadata.
content/docs/references/cloud/index.mdx	Adds cards/links for the newly added cloud reference pages.
OBJECTOS_IMPLEMENTATION.md	Adds an implementation summary and next-steps document for ObjectOS.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

[Copilot]

Adding tenantId as an alias for organizationId introduces ambiguity (both can be provided with different values). Consider normalizing at the schema layer (e.g., transform tenantId → organizationId) and/or adding a refinement that rejects payloads where both are set but not equal, so downstream persistence doesn’t have to guess which one to trust.

[Copilot]

sys_metadata.type is described as the generic envelope for all metadata types, but the select options here omit several canonical metadata kinds (e.g. trigger, validation, hook, page, report, approval, datasource, translation, router, function, service). This will prevent representing those records in sys_metadata. Consider sourcing options from the canonical MetadataTypeSchema (packages/spec/src/kernel/metadata-plugin.zod.ts) or expanding the list to match it.

Suggested change

	{ value: 'view', label: 'View' },
	{ value: 'dashboard', label: 'Dashboard' },
	{ value: 'app', label: 'Application' },
	{ value: 'action', label: 'Action' },
	{ value: 'flow', label: 'Flow' },
	{ value: 'workflow', label: 'Workflow' },
	{ value: 'agent', label: 'AI Agent' },
	{ value: 'tool', label: 'AI Tool' },
	{ value: 'skill', label: 'AI Skill' },
	{ value: 'permission', label: 'Permission Set' },
	{ value: 'profile', label: 'Profile' },
	{ value: 'role', label: 'Role' },
	{ value: 'view', label: 'View' },
	{ value: 'page', label: 'Page' },
	{ value: 'dashboard', label: 'Dashboard' },
	{ value: 'report', label: 'Report' },
	{ value: 'app', label: 'Application' },
	{ value: 'action', label: 'Action' },
	{ value: 'flow', label: 'Flow' },
	{ value: 'workflow', label: 'Workflow' },
	{ value: 'trigger', label: 'Trigger' },
	{ value: 'validation', label: 'Validation' },
	{ value: 'hook', label: 'Hook' },
	{ value: 'approval', label: 'Approval' },
	{ value: 'agent', label: 'AI Agent' },
	{ value: 'tool', label: 'AI Tool' },
	{ value: 'skill', label: 'AI Skill' },
	{ value: 'permission', label: 'Permission Set' },
	{ value: 'profile', label: 'Profile' },
	{ value: 'role', label: 'Role' },
	{ value: 'datasource', label: 'Datasource' },
	{ value: 'translation', label: 'Translation' },
	{ value: 'router', label: 'Router' },
	{ value: 'function', label: 'Function' },
	{ value: 'service', label: 'Service' },

[Copilot]

tools_json and skills_json are modeled as textarea, which stores JSON arrays as strings. Since these are structured configurations and the platform supports Field.json, consider switching them to json fields to keep them typed/queryable and avoid double-encoding.

Suggested change

	tools_json: Field.textarea({
	label: 'Tools (JSON)',
	description: 'Available tools as JSON array',
	}),
	// Skills Configuration
	skills_json: Field.textarea({
	label: 'Skills (JSON)',
	description: 'Available skills as JSON array',
	tools_json: Field.json({
	label: 'Tools',
	description: 'Available tools as a JSON array',
	}),
	// Skills Configuration
	skills_json: Field.json({
	label: 'Skills',
	description: 'Available skills as a JSON array',

[Copilot]

nodes_json, edges_json, and variables_json are modeled as textarea, which forces JSON to be stored as strings. Since flows are inherently structured graphs and the platform supports JSON fields, these should likely use Field.json to keep the data structured and reduce parse/stringify churn.

Suggested change

	nodes_json: Field.textarea({
	label: 'Nodes (JSON)',
	description: 'Flow nodes as JSON',
	}),
	edges_json: Field.textarea({
	label: 'Edges (JSON)',
	description: 'Flow edges as JSON',
	}),
	variables_json: Field.textarea({
	nodes_json: Field.json({
	label: 'Nodes (JSON)',
	description: 'Flow nodes as JSON',
	}),
	edges_json: Field.json({
	label: 'Edges (JSON)',
	description: 'Flow edges as JSON',
	}),
	variables_json: Field.json({

[Copilot]

The registry entries are cast via as unknown as ServiceObject. Since each object is created via ObjectSchema.create(...) (which already returns a ServiceObject shape), these casts hide real type mismatches and reduce safety. Prefer removing the casts (or tightening the exported types) so any schema drift is caught at compile time.

Suggested change

	export const SystemObjects: Record<string, ServiceObject> = {
	// Metadata envelope (source of truth)
	sys_metadata: SysMetadata as unknown as ServiceObject,
	// Data Protocol
	sys_object: SysObject as unknown as ServiceObject,
	// UI Protocol
	sys_view: SysView as unknown as ServiceObject,
	// Automation Protocol
	sys_flow: SysFlow as unknown as ServiceObject,
	// AI Protocol
	sys_agent: SysAgent as unknown as ServiceObject,
	sys_tool: SysTool as unknown as ServiceObject,
	};
	export const SystemObjects = {
	// Metadata envelope (source of truth)
	sys_metadata: SysMetadata,
	// Data Protocol
	sys_object: SysObject,
	// UI Protocol
	sys_view: SysView,
	// Automation Protocol
	sys_flow: SysFlow,
	// AI Protocol
	sys_agent: SysAgent,
	sys_tool: SysTool,
	} satisfies Record<string, ServiceObject>;

[Copilot]

The "Complex Data" fields (fields_json, indexes_json, validations_json, state_machines_json, capabilities_json) are modeled as textarea, which will store JSON as a string. Since the platform supports json fields (Field.json), these should be json types to avoid double-encoding and to keep the data queryable/typed.

Suggested change

	fields_json: Field.textarea({
	label: 'Fields (JSON)',
	description: 'Field definitions as JSON',
	}),
	indexes_json: Field.textarea({
	label: 'Indexes (JSON)',
	description: 'Index definitions as JSON',
	}),
	validations_json: Field.textarea({
	label: 'Validations (JSON)',
	description: 'Validation rules as JSON',
	}),
	state_machines_json: Field.textarea({
	label: 'State Machines (JSON)',
	description: 'State machine definitions as JSON',
	}),
	capabilities_json: Field.textarea({
	fields_json: Field.json({
	label: 'Fields (JSON)',
	description: 'Field definitions as JSON',
	}),
	indexes_json: Field.json({
	label: 'Indexes (JSON)',
	description: 'Index definitions as JSON',
	}),
	validations_json: Field.json({
	label: 'Validations (JSON)',
	description: 'Validation rules as JSON',
	}),
	state_machines_json: Field.json({
	label: 'State Machines (JSON)',
	description: 'State machine definitions as JSON',
	}),
	capabilities_json: Field.json({

[Copilot]

The view configuration fields (columns_json, filters_json, sort_json, config_json) are modeled as textarea, which forces JSON to be stored as strings. Consider using Field.json for these so the configuration remains structured and avoids repeated JSON.parse/JSON.stringify in the runtime and UI.

Suggested change

	columns_json: Field.textarea({
	label: 'Columns (JSON)',
	description: 'Column definitions as JSON',
	}),
	filters_json: Field.textarea({
	label: 'Filters (JSON)',
	description: 'Filter definitions as JSON',
	}),
	sort_json: Field.textarea({
	label: 'Sort (JSON)',
	description: 'Sort configuration as JSON',
	}),
	config_json: Field.textarea({
	columns_json: Field.json({
	label: 'Columns (JSON)',
	description: 'Column definitions as JSON',
	}),
	filters_json: Field.json({
	label: 'Filters (JSON)',
	description: 'Filter definitions as JSON',
	}),
	sort_json: Field.json({
	label: 'Sort (JSON)',
	description: 'Sort configuration as JSON',
	}),
	config_json: Field.json({

[Copilot]

parameters_json is stored as a textarea, which implies JSON-as-string. Since tool parameters are a structured schema, it should likely be a json field. Also, handler_code may be better represented as a code field (Field.code) rather than generic textarea so UI/runtime can treat it as source code consistently.

Suggested change

	parameters_json: Field.textarea({
	label: 'Parameters (JSON)',
	description: 'Tool parameter schema as JSON',
	}),
	// Implementation
	handler_code: Field.textarea({
	parameters_json: Field.json({
	label: 'Parameters (JSON)',
	description: 'Tool parameter schema as JSON',
	}),
	// Implementation
	handler_code: Field.code({

[Copilot]

The README claims ObjectOS provides many sys_* objects (e.g. sys_field, sys_dashboard, sys_app, etc.), but this package currently only defines/exports sys_metadata, sys_object, sys_view, sys_agent, sys_tool, and sys_flow. This mismatch will confuse consumers; consider listing only what is actually shipped (and optionally a separate “planned” section).

Suggested change

	ObjectOS provides system object definitions for all metadata types:
	### Data Protocol
	- `sys_metadata` - Generic metadata envelope
	- `sys_object` - Object definitions
	- `sys_field` - Field definitions
	### UI Protocol
	- `sys_view` - View definitions
	- `sys_dashboard` - Dashboard definitions
	- `sys_app` - App definitions
	- `sys_action` - Action definitions
	### Automation Protocol
	- `sys_flow` - Flow definitions
	- `sys_workflow` - Workflow definitions
	### AI Protocol
	- `sys_agent` - AI Agent definitions
	- `sys_tool` - AI Tool definitions
	- `sys_skill` - AI Skill definitions
	### Security Protocol
	- `sys_permission` - Permission sets
	- `sys_profile` - User profiles
	- `sys_role` - Security roles
	### Identity Protocol
	- `sys_user` - System users
	- `sys_organization` - Organizations
	### System Protocol
	- `sys_environment` - Environments
	- `sys_datasource` - Datasources
	- `sys_package` - Installed packages
	- `sys_translation` - Translation bundles
	ObjectOS currently provides system object definitions for the metadata types shipped in this package:
	### Core Metadata
	- `sys_metadata` - Generic metadata envelope
	- `sys_object` - Object definitions
	- `sys_view` - View definitions
	- `sys_flow` - Flow definitions
	- `sys_agent` - AI Agent definitions
	- `sys_tool` - AI Tool definitions
	Additional system objects for other protocol domains may be added in future releases as the package export surface expands.

[Copilot]

This file looks like PR/CI troubleshooting notes (includes specific commit hashes and step-by-step git commands). Keeping this in the published package directory will likely become stale quickly and adds maintenance overhead; consider moving it to the PR description/internal docs, or removing it once CI is green.