Introduce package registry objects (ADR-0003)

Add first-class control-plane package model: create sys_package and sys_package_version object schemas, and evolve sys_package_installation to point at immutable package_version_id (with denormalized package_id) and richer metadata (status, settings, timestamps, descriptions, indexes). Add package_version_id to sys_metadata and its index. Export and register the new objects from the service-tenant index and tenant plugin, and add tests verifying names, uniqueness indexes, system flags, and field descriptions. These changes implement ADR-0003: treat packages and versions as control-plane first-class entities and enable atomic upgrades/rollbacks by swapping package_version_id.

Author: hotlong

packages/metadata/src/objects/sys-metadata.object.ts

@@ -55,11 +55,24 @@ export const SysMetadataObject = ObjectSchema.create({
       maxLength: 100,
     }),
 
-    /** Package that owns/delivered this metadata */
+    /** Package that owns/delivered this metadata (legacy string identifier, kept for compat) */
     package_id: Field.text({
       label: 'Package ID',
       required: false,
       maxLength: 255,
+      description: 'Legacy package manifest ID string. Use package_version_id for new records.',
+    }),
+
+    /**
+     * FK → sys_package_version (UUID). Set for metadata that belongs to a specific
+     * package release snapshot. NULL = platform-built-in or environment override.
+     */
+    package_version_id: Field.text({
+      label: 'Package Version ID',
+      required: false,
+      maxLength: 255,
+      description:
+        'Foreign key to sys_package_version (UUID). Null = platform-built-in or env-level override.',
     }),
 
     /** Who manages this record: package, platform, or user */
@@ -184,6 +197,7 @@ export const SysMetadataObject = ObjectSchema.create({
     { fields: ['type', 'scope'] },
     { fields: ['organization_id'] },
     { fields: ['env_id'] },
+    { fields: ['package_version_id'] },
     { fields: ['state'] },
     { fields: ['namespace'] },
   ],

packages/services/service-tenant/src/objects/environment-objects.test.ts

@@ -5,6 +5,9 @@ import {
   SysEnvironment,
   SysDatabaseCredential,
   SysEnvironmentMember,
+  SysPackage,
+  SysPackageVersion,
+  SysPackageInstallation,
 } from './index';
 
 describe('control-plane environment objects', () => {
@@ -51,3 +54,68 @@ describe('control-plane environment objects', () => {
     expect(SysEnvironmentMember.isSystem).toBe(true);
   });
 });
+
+describe('control-plane package objects (ADR-0003)', () => {
+  it('registers sys_package and sys_package_version with correct namespaced names', () => {
+    expect(`${SysPackage.namespace}_${SysPackage.name}`).toBe('sys_package');
+    expect(`${SysPackageVersion.namespace}_${SysPackageVersion.name}`).toBe('sys_package_version');
+    expect(`${SysPackageInstallation.namespace}_${SysPackageInstallation.name}`).toBe('sys_package_installation');
+  });
+
+  it('marks all package objects as system objects', () => {
+    expect(SysPackage.isSystem).toBe(true);
+    expect(SysPackageVersion.isSystem).toBe(true);
+    expect(SysPackageInstallation.isSystem).toBe(true);
+  });
+
+  it('sys_package has UNIQUE manifest_id index', () => {
+    const idx = SysPackage.indexes ?? [];
+    expect(
+      idx.some((i: any) => i.unique && i.fields.join(',') === 'manifest_id'),
+    ).toBe(true);
+  });
+
+  it('sys_package_version has UNIQUE (package_id, version) index', () => {
+    const idx = SysPackageVersion.indexes ?? [];
+    expect(
+      idx.some((i: any) => i.unique && i.fields.join(',') === 'package_id,version'),
+    ).toBe(true);
+  });
+
+  it('sys_package_installation has UNIQUE (environment_id, package_id) index', () => {
+    const idx = SysPackageInstallation.indexes ?? [];
+    expect(
+      idx.some((i: any) => i.unique && i.fields.join(',') === 'environment_id,package_id'),
+    ).toBe(true);
+  });
+
+  it('sys_package_installation has package_version_id field (not a version string)', () => {
+    expect(SysPackageInstallation.fields).toHaveProperty('package_version_id');
+    expect(SysPackageInstallation.fields).not.toHaveProperty('upgrade_history');
+  });
+
+  it('sys_package_installation has package_version_id index', () => {
+    const idx = SysPackageInstallation.indexes ?? [];
+    expect(
+      idx.some((i: any) => i.fields.join(',') === 'package_version_id'),
+    ).toBe(true);
+  });
+
+  it('gives every field on sys_package a .description', () => {
+    for (const [name, field] of Object.entries(SysPackage.fields)) {
+      expect((field as any).description, `sys_package.${name} missing description`).toBeTruthy();
+    }
+  });
+
+  it('gives every field on sys_package_version a .description', () => {
+    for (const [name, field] of Object.entries(SysPackageVersion.fields)) {
+      expect((field as any).description, `sys_package_version.${name} missing description`).toBeTruthy();
+    }
+  });
+
+  it('gives every field on sys_package_installation a .description', () => {
+    for (const [name, field] of Object.entries(SysPackageInstallation.fields)) {
+      expect((field as any).description, `sys_package_installation.${name} missing description`).toBeTruthy();
+    }
+  });
+});

packages/services/service-tenant/src/objects/index.ts

@@ -9,6 +9,7 @@ export * from './sys-environment-member.object';
 // docs/adr/0002-environment-database-isolation.md for the migration path.
 export * from './sys-tenant-database.object';
 
-// Package installation registry (lives in control plane for now; will move
-// into each environment's data plane in v5.0 per ADR-0002).
+// Package registry (Control Plane, permanent — see ADR-0003).
+export * from './sys-package.object';
+export * from './sys-package-version.object';
 export * from './sys-package-installation.object';

packages/services/service-tenant/src/objects/sys-package-installation.object.ts

@@ -5,10 +5,20 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
 /**
  * sys_package_installation — Per-environment package installation record.
  *
- * Tracks which packages (business solutions) are installed in each environment.
- * Stored in the **Control Plane** (sys namespace → turso driver) so that all
- * environment installations are visible from a single query. Environment DBs
- * contain only business data rows — zero system tables.
+ * Models the pairing between an environment and a specific, immutable package
+ * version snapshot (`sys_package_version`). Only one version of a given package
+ * may be active per environment at a time (enforced by UNIQUE on
+ * `(environment_id, package_id)`).
+ *
+ * **Upgrade** = atomic UPDATE of `package_version_id` to a newer version UUID.
+ * **Rollback** = atomic UPDATE of `package_version_id` to an older version UUID.
+ * Version history is tracked via the sequence of `package_version_id` changes
+ * on this row (and an optional sys_package_installation_history audit table).
+ *
+ * **Stored in the Control Plane DB (not in environment DBs).**
+ * Environment DBs contain only business data rows — zero system tables.
+ *
+ * See `docs/adr/0003-package-as-first-class-citizen.md` for the full rationale.
  *
  * @namespace sys
  */
@@ -19,106 +29,111 @@ export const SysPackageInstallation = ObjectSchema.create({
   pluralLabel: 'Package Installations',
   icon: 'package',
   isSystem: true,
-  description: 'Per-environment package installation registry (sys_package_installation)',
+  description: 'Per-environment package installation registry (sys_package_installation).',
   titleFormat: '{package_id} @ {environment_id}',
-  compactLayout: ['package_id', 'environment_id', 'version', 'status'],
+  compactLayout: ['package_version_id', 'environment_id', 'status', 'installed_at'],
 
   fields: {
     id: Field.text({
       label: 'Installation ID',
       required: true,
       readonly: true,
-      description: 'UUID-based installation identifier',
+      description: 'UUID of this installation record (stable, never reused).',
     }),
 
     created_at: Field.datetime({
       label: 'Created At',
       defaultValue: 'NOW()',
       readonly: true,
+      description: 'Creation timestamp (ISO-8601).',
     }),
 
     updated_at: Field.datetime({
       label: 'Updated At',
       defaultValue: 'NOW()',
       readonly: true,
+      description: 'Last update timestamp — changes on upgrade, rollback, enable/disable (ISO-8601).',
     }),
 
     environment_id: Field.text({
       label: 'Environment ID',
       required: true,
-      description: 'Foreign key to sys__environment',
+      description: 'Foreign key to sys_environment (UUID). The environment that owns this installation.',
     }),
 
-    package_id: Field.text({
-      label: 'Package ID',
+    package_version_id: Field.text({
+      label: 'Package Version ID',
       required: true,
-      maxLength: 255,
-      description: 'Manifest ID of the installed package (reverse-domain, e.g. com.example.crm)',
+      description:
+        'Foreign key to sys_package_version (UUID). The specific, immutable release snapshot ' +
+        'currently installed in this environment. Upgrading = swapping this field to a newer ' +
+        'version UUID. Rollback = swapping to an older version UUID.',
     }),
 
-    version: Field.text({
-      label: 'Version',
+    package_id: Field.text({
+      label: 'Package ID',
       required: true,
-      maxLength: 50,
-      description: 'Installed package version (semver)',
+      description:
+        'Foreign key to sys_package (UUID). Denormalized from the linked package_version row ' +
+        'at install time to enforce the UNIQUE (environment_id, package_id) constraint without a JOIN.',
     }),
 
     status: Field.select({
       label: 'Status',
       required: true,
+      defaultValue: 'installed',
+      description: 'Current lifecycle status of this installation within the environment.',
       options: [
         { value: 'installed', label: 'Installed' },
         { value: 'installing', label: 'Installing' },
         { value: 'upgrading', label: 'Upgrading' },
         { value: 'disabled', label: 'Disabled' },
         { value: 'error', label: 'Error' },
       ],
-      defaultValue: 'installed',
     }),
 
     enabled: Field.boolean({
       label: 'Enabled',
       required: true,
       defaultValue: true,
-      description: 'Whether the package is currently active in this environment',
+      description:
+        'Whether the package metadata is actively loaded into this environment. ' +
+        'Disabled packages are installed but their schema is not visible to the runtime.',
+    }),
+
+    settings: Field.textarea({
+      label: 'Settings',
+      required: false,
+      description:
+        'JSON-serialized per-installation configuration overrides. ' +
+        'Keys mirror the package manifest configurationSchema.properties.',
     }),
 
     installed_at: Field.datetime({
       label: 'Installed At',
       required: true,
       defaultValue: 'NOW()',
+      description: 'Timestamp when this installation was first created (ISO-8601).',
     }),
 
     installed_by: Field.text({
       label: 'Installed By',
       required: false,
-      description: 'User ID who installed the package',
+      description: 'User ID who performed the initial install. Null for system-automated installs.',
     }),
 
     error_message: Field.textarea({
       label: 'Error Message',
       required: false,
-      description: 'Error details when status is error',
-    }),
-
-    settings: Field.textarea({
-      label: 'Settings',
-      required: false,
-      description: 'JSON-serialized per-installation configuration',
-    }),
-
-    upgrade_history: Field.textarea({
-      label: 'Upgrade History',
-      required: false,
-      defaultValue: '[]',
-      description: 'JSON array of version upgrade records',
+      description: 'Error details when status is error. Cleared on next successful install/upgrade.',
     }),
   },
 
   indexes: [
     { fields: ['environment_id', 'package_id'], unique: true },
     { fields: ['environment_id'] },
     { fields: ['package_id'] },
+    { fields: ['package_version_id'] },
     { fields: ['status'] },
   ],