feat(metadata): add metadata persistence schema and types for unified storage

Author: hotlong

packages/spec/src/system/index.ts

@@ -35,6 +35,8 @@ export * from './worker.zod';
 export * from './notification.zod';
 export * from './translation.zod';
 export * from './collaboration.zod';
+export * from './metadata-persistence.zod';
+export * from './service-registry.zod';
 
 // Types
 export * from './types';

packages/spec/src/system/metadata-persistence.zod.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+
+/**
+ * Metadata Scope Enum
+ * Defines the lifecycle and mutability of a metadata item.
+ */
+export const MetadataScopeSchema = z.enum([
+  'system',   // Defined in Code (Files). Read-only at runtime. Upgraded via deployment.
+  'platform', // Defined in DB (Global). admin-configured. Overrides system.
+  'user',     // Defined in DB (Personal). User-configured. Overrides platform/system.
+]);
+
+/**
+ * Metadata Lifecycle State
+ */
+export const MetadataStateSchema = z.enum([
+  'draft',    // Work in progress, not active
+  'active',   // Live and running
+  'archived', // Soft deleted
+  'deprecated' // Running but flagged for removal
+]);
+
+/**
+ * Unified Metadata Persistence Protocol
+ * 
+ * Defines the standardized envelope for storing ANY metadata item (Object, View, Flow)
+ * in the database (e.g. `_framework_metadata` or generic `metadata` table).
+ * 
+ * This treats "Metadata as Data".
+ */
+export const MetadataRecordSchema = z.object({
+  /** Primary Key (UUID) */
+  _id: z.string(),
+  
+  /** 
+   * Machine Name 
+   * The unique identifier used in code references (e.g. "account_list_view").
+   */
+  name: z.string(),
+  
+  /**
+   * Metadata Type
+   * e.g. "object", "view", "permission_set", "flow"
+   */
+  type: z.string(),
+  
+  /**
+   * Namespace / Module
+   * Groups metadata into packages (e.g. "crm", "finance", "core").
+   */
+  namespace: z.string().default('default'),
+  
+  /**
+   * Ownership differentiation
+   */
+  scope: MetadataScopeSchema.default('platform'),
+  
+  /**
+   * The Payload
+   * Stores the actual configuration JSON.
+   * This field holds the value of `ViewSchema`, `ObjectSchema`, etc.
+   */
+  metadata: z.record(z.string(), z.any()),
+
+  /**
+   * Extension / Merge Strategy
+   * If this record overrides a system record, how should it be applied?
+   */
+  extends: z.string().optional().describe('Name of the parent metadata to extend/override'),
+  strategy: z.enum(['merge', 'replace']).default('merge'),
+
+  /** Owner (for user-scope items) */
+  owner: z.string().optional(),
+  
+  /** State */
+  state: MetadataStateSchema.default('active'),
+  
+  /** Audit */
+  created_by: z.string().optional(),
+  created_at: z.date().optional(),
+  updated_by: z.string().optional(),
+  updated_at: z.date().optional(),
+});
+
+export type MetadataRecord = z.infer<typeof MetadataRecordSchema>;
+export type MetadataScope = z.infer<typeof MetadataScopeSchema>;