Phase 2 tasks: create shared metadata-types, rename kernel security schemas, rename realtime presence schemas

Copilot · hotlong · Copilot · commit c3d0cf257900 · 2026-02-07T18:15:45.000Z
Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/packages/spec/json-schema/api/RealtimePresence.json b/packages/spec/json-schema/api/RealtimePresence.json
@@ -1,7 +1,7 @@
 {
-  "$ref": "#/definitions/Presence",
+  "$ref": "#/definitions/RealtimePresence",
   "definitions": {
-    "Presence": {
+    "RealtimePresence": {
       "type": "object",
       "properties": {
         "userId": {
diff --git a/packages/spec/json-schema/api/RealtimePresenceStatus.json b/packages/spec/json-schema/api/RealtimePresenceStatus.json
@@ -1,7 +1,7 @@
 {
-  "$ref": "#/definitions/PresenceStatus",
+  "$ref": "#/definitions/RealtimePresenceStatus",
   "definitions": {
-    "PresenceStatus": {
+    "RealtimePresenceStatus": {
       "type": "string",
       "enum": [
         "online",
diff --git a/packages/spec/json-schema/kernel/KernelSecurityPolicy.json b/packages/spec/json-schema/kernel/KernelSecurityPolicy.json
@@ -1,7 +1,7 @@
 {
-  "$ref": "#/definitions/SecurityPolicy",
+  "$ref": "#/definitions/KernelSecurityPolicy",
   "definitions": {
-    "SecurityPolicy": {
+    "KernelSecurityPolicy": {
       "type": "object",
       "properties": {
         "csp": {
diff --git a/packages/spec/json-schema/kernel/KernelSecurityScanResult.json b/packages/spec/json-schema/kernel/KernelSecurityScanResult.json
@@ -1,7 +1,7 @@
 {
-  "$ref": "#/definitions/SecurityScanResult",
+  "$ref": "#/definitions/KernelSecurityScanResult",
   "definitions": {
-    "SecurityScanResult": {
+    "KernelSecurityScanResult": {
       "type": "object",
       "properties": {
         "timestamp": {
diff --git a/packages/spec/json-schema/kernel/KernelSecurityVulnerability.json b/packages/spec/json-schema/kernel/KernelSecurityVulnerability.json
@@ -1,7 +1,7 @@
 {
-  "$ref": "#/definitions/SecurityVulnerability",
+  "$ref": "#/definitions/KernelSecurityVulnerability",
   "definitions": {
-    "SecurityVulnerability": {
+    "KernelSecurityVulnerability": {
       "type": "object",
       "properties": {
         "cve": {
diff --git a/packages/spec/json-schema/shared/BaseMetadataRecord.json b/packages/spec/json-schema/shared/BaseMetadataRecord.json
@@ -0,0 +1,42 @@
+{
+  "$ref": "#/definitions/BaseMetadataRecord",
+  "definitions": {
+    "BaseMetadataRecord": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique metadata record identifier"
+        },
+        "type": {
+          "type": "string",
+          "description": "Metadata type (e.g. \"object\", \"view\", \"flow\")"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 2,
+          "pattern": "^[a-z][a-z0-9_]*$",
+          "description": "Machine name (snake_case)"
+        },
+        "format": {
+          "type": "string",
+          "enum": [
+            "yaml",
+            "json",
+            "typescript",
+            "javascript"
+          ],
+          "description": "Source file format"
+        }
+      },
+      "required": [
+        "id",
+        "type",
+        "name"
+      ],
+      "additionalProperties": false,
+      "description": "Base metadata record fields shared across kernel and system"
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}
diff --git a/packages/spec/json-schema/shared/MetadataFormat.json b/packages/spec/json-schema/shared/MetadataFormat.json
@@ -0,0 +1,16 @@
+{
+  "$ref": "#/definitions/MetadataFormat",
+  "definitions": {
+    "MetadataFormat": {
+      "type": "string",
+      "enum": [
+        "yaml",
+        "json",
+        "typescript",
+        "javascript"
+      ],
+      "description": "Metadata file format"
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}
diff --git a/packages/spec/src/api/realtime.test.ts b/packages/spec/src/api/realtime.test.ts
@@ -4,12 +4,12 @@ import {
   RealtimeEventType,
   SubscriptionEventSchema,
   SubscriptionSchema,
-  PresenceStatus,
-  PresenceSchema,
+  RealtimePresenceStatus,
+  RealtimePresenceSchema,
   RealtimeAction,
   RealtimeEventSchema,
   type Subscription,
-  type Presence,
+  type RealtimePresence,
   type RealtimeEvent,
 } from './realtime.zod';
 
@@ -190,29 +190,29 @@ describe('SubscriptionSchema', () => {
   });
 });
 
-describe('PresenceStatus', () => {
+describe('RealtimePresenceStatus', () => {
   it('should accept valid presence statuses', () => {
-    expect(() => PresenceStatus.parse('online')).not.toThrow();
-    expect(() => PresenceStatus.parse('away')).not.toThrow();
-    expect(() => PresenceStatus.parse('offline')).not.toThrow();
+    expect(() => RealtimePresenceStatus.parse('online')).not.toThrow();
+    expect(() => RealtimePresenceStatus.parse('away')).not.toThrow();
+    expect(() => RealtimePresenceStatus.parse('offline')).not.toThrow();
   });
 
   it('should reject invalid presence statuses', () => {
-    expect(() => PresenceStatus.parse('busy')).toThrow();
-    expect(() => PresenceStatus.parse('idle')).toThrow();
-    expect(() => PresenceStatus.parse('')).toThrow();
+    expect(() => RealtimePresenceStatus.parse('busy')).toThrow();
+    expect(() => RealtimePresenceStatus.parse('idle')).toThrow();
+    expect(() => RealtimePresenceStatus.parse('')).toThrow();
   });
 });
 
-describe('PresenceSchema', () => {
+describe('RealtimePresenceSchema', () => {
   it('should accept valid minimal presence', () => {
-    const presence: Presence = {
+    const presence: RealtimePresence = {
       userId: 'user-123',
       status: 'online',
       lastSeen: '2024-01-15T10:30:00Z',
     };
 
-    expect(() => PresenceSchema.parse(presence)).not.toThrow();
+    expect(() => RealtimePresenceSchema.parse(presence)).not.toThrow();
   });
 
   it('should accept presence with metadata', () => {
@@ -227,13 +227,13 @@ describe('PresenceSchema', () => {
       },
     };
 
-    const parsed = PresenceSchema.parse(presence);
+    const parsed = RealtimePresenceSchema.parse(presence);
     expect(parsed.metadata).toBeDefined();
     expect(parsed.metadata?.currentPage).toBe('/dashboard');
   });
 
   it('should accept all presence statuses', () => {
-    const statuses: Array<Presence['status']> = ['online', 'away', 'offline'];
+    const statuses: Array<RealtimePresence['status']> = ['online', 'away', 'offline'];
 
     statuses.forEach(status => {
       const presence = {
@@ -242,37 +242,37 @@ describe('PresenceSchema', () => {
         lastSeen: '2024-01-15T10:30:00Z',
       };
 
-      const parsed = PresenceSchema.parse(presence);
+      const parsed = RealtimePresenceSchema.parse(presence);
       expect(parsed.status).toBe(status);
     });
   });
 
   it('should validate datetime format', () => {
-    expect(() => PresenceSchema.parse({
+    expect(() => RealtimePresenceSchema.parse({
       userId: 'user-123',
       status: 'online',
       lastSeen: 'not-a-datetime',
     })).toThrow();
 
-    expect(() => PresenceSchema.parse({
+    expect(() => RealtimePresenceSchema.parse({
       userId: 'user-123',
       status: 'online',
       lastSeen: '2024-01-15T10:30:00Z',
     })).not.toThrow();
   });
 
   it('should reject presence without required fields', () => {
-    expect(() => PresenceSchema.parse({
+    expect(() => RealtimePresenceSchema.parse({
       status: 'online',
       lastSeen: '2024-01-15T10:30:00Z',
     })).toThrow();
 
-    expect(() => PresenceSchema.parse({
+    expect(() => RealtimePresenceSchema.parse({
       userId: 'user-123',
       lastSeen: '2024-01-15T10:30:00Z',
     })).toThrow();
 
-    expect(() => PresenceSchema.parse({
+    expect(() => RealtimePresenceSchema.parse({
       userId: 'user-123',
       status: 'online',
     })).toThrow();
diff --git a/packages/spec/src/api/realtime.zod.ts b/packages/spec/src/api/realtime.zod.ts
@@ -52,26 +52,26 @@ export type Subscription = z.infer<typeof SubscriptionSchema>;
  * Presence Status Enum
  * User online/offline status
  */
-export const PresenceStatus = z.enum([
+export const RealtimePresenceStatus = z.enum([
   'online',
   'away',
   'offline',
 ]);
 
-export type PresenceStatus = z.infer<typeof PresenceStatus>;
+export type RealtimePresenceStatus = z.infer<typeof RealtimePresenceStatus>;
 
 /**
  * Presence Schema
  * Tracks user online status and metadata
  */
-export const PresenceSchema = z.object({
+export const RealtimePresenceSchema = z.object({
   userId: z.string().describe('User identifier'),
-  status: PresenceStatus.describe('Current presence status'),
+  status: RealtimePresenceStatus.describe('Current presence status'),
   lastSeen: z.string().datetime().describe('ISO 8601 datetime of last activity'),
   metadata: z.record(z.string(), z.any()).optional().describe('Custom presence data (e.g., current page, custom status)'),
 });
 
-export type Presence = z.infer<typeof PresenceSchema>;
+export type RealtimePresence = z.infer<typeof RealtimePresenceSchema>;
 
 /**
  * Realtime Action Enum
diff --git a/packages/spec/src/kernel/plugin-security-advanced.test.ts b/packages/spec/src/kernel/plugin-security-advanced.test.ts
@@ -4,7 +4,7 @@ import {
   SandboxConfigSchema,
   PermissionSchema,
   PermissionSetSchema,
-  SecurityPolicySchema,
+  KernelSecurityPolicySchema,
   PluginSecurityManifestSchema,
 } from './plugin-security-advanced.zod';
 
@@ -218,7 +218,7 @@ describe('Plugin Security Advanced Schemas', () => {
     });
   });
 
-  describe('SecurityPolicySchema', () => {
+  describe('KernelSecurityPolicySchema', () => {
     it('should validate comprehensive security policy', () => {
       const policy = {
         csp: {
@@ -257,7 +257,7 @@ describe('Plugin Security Advanced Schemas', () => {
           retention: 90,
         },
       };
-      const result = SecurityPolicySchema.parse(policy);
+      const result = KernelSecurityPolicySchema.parse(policy);
       expect(result.rateLimit?.enabled).toBe(true);
       expect(result.authentication?.required).toBe(true);
       expect(result.encryption?.dataAtRest).toBe(true);
diff --git a/packages/spec/src/kernel/plugin-security-advanced.zod.ts b/packages/spec/src/kernel/plugin-security-advanced.zod.ts
@@ -369,7 +369,7 @@ export const SandboxConfigSchema = z.object({
  * Security Vulnerability
  * Represents a known security vulnerability
  */
-export const SecurityVulnerabilitySchema = z.object({
+export const KernelSecurityVulnerabilitySchema = z.object({
   /**
    * CVE identifier
    */
@@ -460,7 +460,7 @@ export const SecurityVulnerabilitySchema = z.object({
  * Security Scan Result
  * Result of security scanning
  */
-export const SecurityScanResultSchema = z.object({
+export const KernelSecurityScanResultSchema = z.object({
   /**
    * Scan timestamp
    */
@@ -482,7 +482,7 @@ export const SecurityScanResultSchema = z.object({
   /**
    * Vulnerabilities found
    */
-  vulnerabilities: z.array(SecurityVulnerabilitySchema).optional(),
+  vulnerabilities: z.array(KernelSecurityVulnerabilitySchema).optional(),
   
   /**
    * Code quality issues
@@ -502,7 +502,7 @@ export const SecurityScanResultSchema = z.object({
   dependencyVulnerabilities: z.array(z.object({
     package: z.string(),
     version: z.string(),
-    vulnerability: SecurityVulnerabilitySchema,
+    vulnerability: KernelSecurityVulnerabilitySchema,
   })).optional(),
   
   /**
@@ -534,7 +534,7 @@ export const SecurityScanResultSchema = z.object({
  * Security Policy
  * Defines security policies for plugin
  */
-export const SecurityPolicySchema = z.object({
+export const KernelSecurityPolicySchema = z.object({
   /**
    * Content Security Policy
    */
@@ -633,17 +633,17 @@ export const PluginSecurityManifestSchema = z.object({
   /**
    * Security policy
    */
-  policy: SecurityPolicySchema.optional(),
+  policy: KernelSecurityPolicySchema.optional(),
   
   /**
    * Security scan results
    */
-  scanResults: z.array(SecurityScanResultSchema).optional(),
+  scanResults: z.array(KernelSecurityScanResultSchema).optional(),
   
   /**
    * Known vulnerabilities
    */
-  vulnerabilities: z.array(SecurityVulnerabilitySchema).optional(),
+  vulnerabilities: z.array(KernelSecurityVulnerabilitySchema).optional(),
   
   /**
    * Code signing
@@ -694,8 +694,8 @@ export type Permission = z.infer<typeof PermissionSchema>;
 export type PermissionSet = z.infer<typeof PermissionSetSchema>;
 export type RuntimeConfig = z.infer<typeof RuntimeConfigSchema>;
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
-export type SecurityVulnerability = z.infer<typeof SecurityVulnerabilitySchema>;
-export type SecurityScanResult = z.infer<typeof SecurityScanResultSchema>;
-export type SecurityPolicy = z.infer<typeof SecurityPolicySchema>;
+export type KernelSecurityVulnerability = z.infer<typeof KernelSecurityVulnerabilitySchema>;
+export type KernelSecurityScanResult = z.infer<typeof KernelSecurityScanResultSchema>;
+export type KernelSecurityPolicy = z.infer<typeof KernelSecurityPolicySchema>;
 export type PluginTrustLevel = z.infer<typeof PluginTrustLevelSchema>;
 export type PluginSecurityManifest = z.infer<typeof PluginSecurityManifestSchema>;
diff --git a/packages/spec/src/shared/index.ts b/packages/spec/src/shared/index.ts
@@ -7,3 +7,4 @@ export * from './identifiers.zod';
 export * from './mapping.zod';
 export * from './http.zod';
 export * from './enums.zod';
+export * from './metadata-types.zod';
diff --git a/packages/spec/src/shared/metadata-types.zod.ts b/packages/spec/src/shared/metadata-types.zod.ts
@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { SnakeCaseIdentifierSchema } from './identifiers.zod';
+
+// ============================================================================
+// Shared Metadata Types
+// ============================================================================
+
+/** Supported metadata file formats */
+export const MetadataFormatSchema = z.enum(['yaml', 'json', 'typescript', 'javascript'])
+  .describe('Metadata file format');
+export type MetadataFormat = z.infer<typeof MetadataFormatSchema>;
+
+/** Base metadata record fields shared across kernel and system layers */
+export const BaseMetadataRecordSchema = z.object({
+  id: z.string().describe('Unique metadata record identifier'),
+  type: z.string().describe('Metadata type (e.g. "object", "view", "flow")'),
+  name: SnakeCaseIdentifierSchema.describe('Machine name (snake_case)'),
+  format: MetadataFormatSchema.optional().describe('Source file format'),
+}).describe('Base metadata record fields shared across kernel and system');
+export type BaseMetadataRecord = z.infer<typeof BaseMetadataRecordSchema>;
