@objectstack/platform-objects 4.2.0 → 5.0.0

package/dist/metadata/index.d.ts

@@ -598,6 +598,12 @@ declare const SysMetadataObject: Omit<{
     recordTypes?: string[] | undefined;
     sharingModel?: "read" | "full" | "private" | "read_write" | undefined;
     keyPrefix?: string | undefined;
+    detail?: {
+        [x: string]: unknown;
+        renderViaSchema?: boolean | undefined;
+        hideReferenceRail?: boolean | undefined;
+        hideRelatedTab?: boolean | undefined;
+    } | undefined;
     actions?: {
         name: string;
         label: string;
@@ -3506,7 +3512,7 @@ declare const SysMetadataObject: Omit<{
             readonly index?: boolean | undefined;
             readonly type: "number";
         };
-        /** Content checksum for change detection */
+        /** Content checksum for change detection (e.g. `sha256:<64 hex>` = 71 chars) */
         readonly checksum: {
             readonly readonly?: boolean | undefined;
             readonly format?: string | undefined;
@@ -4763,18 +4769,43 @@ declare const SysMetadataObject: Omit<{
 }, "fields">;
 
 /**
- * sys_metadata_history — Metadata Version History Object
+ * sys_metadata_history — Metadata Version History / Event Log
  *
- * Stores historical snapshots of metadata changes for version tracking,
- * audit trail, and rollback capabilities.
+ * Append-only durable log of every overlay change made through
+ * `SysMetadataRepository.put` / `delete` (ADR-0008 §10 M1). Each row is a
+ * single event in the per-organisation event log; rows are NEVER
+ * mutated after insertion. The legacy `DatabaseLoader` writes the same
+ * shape from its own put/restore code paths.
  *
- * This is a system object (isSystem: true) — protected from deletion and
- * automatically provisioned when metadata history is enabled.
+ * ─────────────────────────────────────────────────────────────────────
+ *  Key design points (ADR-0008 §0 amendment + M1):
+ *
+ *  • Keyed by `(organization_id, type, name)` only — `project_id` was
+ *    removed in the branch/project-removal amendment.
+ *
+ *  • `event_seq` is the per-org monotonic event-log cursor. Producers
+ *    compute `MAX(event_seq) + 1 WHERE organization_id = X` inside the
+ *    same transaction as the parent `sys_metadata` write.
+ *
+ *  • `version` is the per-(org,type,name) lineage counter. Producers
+ *    compute `MAX(version) + 1 WHERE organization_id = X AND type = T
+ *    AND name = N` so delete + recreate continues incrementing instead
+ *    of restarting at 1.
+ *
+ *  • `metadata_id` is plain `text` (not a `lookup`) so DELETE rows can
+ *    keep the now-orphaned parent id for forensic auditing without a
+ *    foreign-key constraint blocking the hard delete.
+ *
+ *  • `metadata` / `checksum` are nullable — DELETE rows have no body or
+ *    hash. Readers must tolerate null on both columns.
  *
- * Each record represents a single version snapshot of a metadata item,
- * created whenever the metadata is modified, published, or reverted.
+ *  • `source` records the producer ('sys-metadata-repo', 'fs',
+ *    'studio', …) and feeds MetadataEvent.source on history() reads.
  *
- * @see MetadataHistoryRecordSchema in metadata-persistence.zod.ts
+ *  Indexes are purpose-built for the two dominant read patterns:
+ *    1. per-item history view  → `(organization_id, type, name, version)`
+ *    2. org-wide event replay   → `(organization_id, event_seq)`
+ * ─────────────────────────────────────────────────────────────────────
  */
 declare const SysMetadataHistoryObject: Omit<{
     name: string;
@@ -5360,6 +5391,12 @@ declare const SysMetadataHistoryObject: Omit<{
     recordTypes?: string[] | undefined;
     sharingModel?: "read" | "full" | "private" | "read_write" | undefined;
     keyPrefix?: string | undefined;
+    detail?: {
+        [x: string]: unknown;
+        renderViaSchema?: boolean | undefined;
+        hideReferenceRail?: boolean | undefined;
+        hideRelatedTab?: boolean | undefined;
+    } | undefined;
     actions?: {
         name: string;
         label: string;
@@ -5442,7 +5479,7 @@ declare const SysMetadataHistoryObject: Omit<{
     readonly icon: "history";
     readonly isSystem: true;
     readonly managedBy: "system";
-    readonly description: "Version history and audit trail for metadata changes";
+    readonly description: "Durable event log of metadata overlay changes (per-org, append-only)";
     readonly fields: {
         /** Primary Key (UUID) */
         readonly id: {
@@ -5620,7 +5657,188 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly index?: boolean | undefined;
             readonly type: "text";
         };
-        /** Foreign key to sys_metadata.id */
+        /** Per-org monotonic event sequence (durable cursor for replay). */
+        readonly event_seq: {
+            readonly readonly?: boolean | undefined;
+            readonly format?: string | undefined;
+            readonly options?: {
+                label: string;
+                value: string;
+                color?: string | undefined;
+                default?: boolean | undefined;
+            }[] | undefined;
+            readonly description?: string | undefined;
+            readonly label?: string | undefined;
+            readonly name?: string | undefined;
+            readonly precision?: number | undefined;
+            readonly required?: boolean | undefined;
+            readonly multiple?: boolean | undefined;
+            readonly dependencies?: string[] | undefined;
+            readonly theme?: string | undefined;
+            readonly externalId?: boolean | undefined;
+            readonly system?: boolean | undefined;
+            readonly min?: number | undefined;
+            readonly max?: number | undefined;
+            readonly group?: string | undefined;
+            readonly encryptionConfig?: {
+                enabled: boolean;
+                algorithm: "aes-256-gcm" | "aes-256-cbc" | "chacha20-poly1305";
+                keyManagement: {
+                    provider: "local" | "aws-kms" | "azure-key-vault" | "gcp-kms" | "hashicorp-vault";
+                    keyId?: string | undefined;
+                    rotationPolicy?: {
+                        enabled: boolean;
+                        frequencyDays: number;
+                        retainOldVersions: number;
+                        autoRotate: boolean;
+                    } | undefined;
+                };
+                scope: "record" | "field" | "table" | "database";
+                deterministicEncryption: boolean;
+                searchableEncryption: boolean;
+            } | undefined;
+            readonly columnName?: string | undefined;
+            readonly searchable?: boolean | undefined;
+            readonly unique?: boolean | undefined;
+            readonly defaultValue?: unknown;
+            readonly maxLength?: number | undefined;
+            readonly minLength?: number | undefined;
+            readonly scale?: number | undefined;
+            readonly reference?: string | undefined;
+            readonly referenceFilters?: string[] | undefined;
+            readonly writeRequiresMasterRead?: boolean | undefined;
+            readonly deleteBehavior?: "set_null" | "cascade" | "restrict" | undefined;
+            readonly expression?: {
+                dialect: "cel" | "js" | "cron" | "template";
+                source?: string | undefined;
+                ast?: unknown;
+                meta?: {
+                    rationale?: string | undefined;
+                    generatedBy?: string | undefined;
+                } | undefined;
+            } | undefined;
+            readonly summaryOperations?: {
+                object: string;
+                field: string;
+                function: "min" | "max" | "count" | "sum" | "avg";
+            } | undefined;
+            readonly language?: string | undefined;
+            readonly lineNumbers?: boolean | undefined;
+            readonly maxRating?: number | undefined;
+            readonly allowHalf?: boolean | undefined;
+            readonly displayMap?: boolean | undefined;
+            readonly allowGeocoding?: boolean | undefined;
+            readonly addressFormat?: "us" | "uk" | "international" | undefined;
+            readonly colorFormat?: "hex" | "rgb" | "rgba" | "hsl" | undefined;
+            readonly allowAlpha?: boolean | undefined;
+            readonly presetColors?: string[] | undefined;
+            readonly step?: number | undefined;
+            readonly showValue?: boolean | undefined;
+            readonly marks?: Record<string, string> | undefined;
+            readonly barcodeFormat?: "qr" | "ean13" | "ean8" | "code128" | "code39" | "upca" | "upce" | undefined;
+            readonly qrErrorCorrection?: "L" | "M" | "Q" | "H" | undefined;
+            readonly displayValue?: boolean | undefined;
+            readonly allowScanning?: boolean | undefined;
+            readonly currencyConfig?: {
+                precision: number;
+                currencyMode: "fixed" | "dynamic";
+                defaultCurrency: string;
+            } | undefined;
+            readonly vectorConfig?: {
+                dimensions: number;
+                distanceMetric: "cosine" | "euclidean" | "dotProduct" | "manhattan";
+                normalized: boolean;
+                indexed: boolean;
+                indexType?: "flat" | "hnsw" | "ivfflat" | undefined;
+            } | undefined;
+            readonly fileAttachmentConfig?: {
+                virusScan: boolean;
+                virusScanOnUpload: boolean;
+                quarantineOnThreat: boolean;
+                allowMultiple: boolean;
+                allowReplace: boolean;
+                allowDelete: boolean;
+                requireUpload: boolean;
+                extractMetadata: boolean;
+                extractText: boolean;
+                versioningEnabled: boolean;
+                publicRead: boolean;
+                presignedUrlExpiry: number;
+                minSize?: number | undefined;
+                maxSize?: number | undefined;
+                allowedTypes?: string[] | undefined;
+                blockedTypes?: string[] | undefined;
+                allowedMimeTypes?: string[] | undefined;
+                blockedMimeTypes?: string[] | undefined;
+                virusScanProvider?: "custom" | "clamav" | "virustotal" | "metadefender" | undefined;
+                storageProvider?: string | undefined;
+                storageBucket?: string | undefined;
+                storagePrefix?: string | undefined;
+                imageValidation?: {
+                    generateThumbnails: boolean;
+                    preserveMetadata: boolean;
+                    autoRotate: boolean;
+                    minWidth?: number | undefined;
+                    maxWidth?: number | undefined;
+                    minHeight?: number | undefined;
+                    maxHeight?: number | undefined;
+                    aspectRatio?: string | undefined;
+                    thumbnailSizes?: {
+                        name: string;
+                        width: number;
+                        height: number;
+                        crop: boolean;
+                    }[] | undefined;
+                } | undefined;
+                maxVersions?: number | undefined;
+            } | undefined;
+            readonly maskingRule?: {
+                field: string;
+                strategy: "partial" | "hash" | "redact" | "tokenize" | "randomize" | "nullify" | "substitute";
+                preserveFormat: boolean;
+                preserveLength: boolean;
+                pattern?: string | undefined;
+                roles?: string[] | undefined;
+                exemptRoles?: string[] | undefined;
+            } | undefined;
+            readonly auditTrail?: boolean | undefined;
+            readonly cached?: {
+                enabled: boolean;
+                ttl: number;
+                invalidateOn: string[];
+            } | undefined;
+            readonly dataQuality?: {
+                uniqueness: boolean;
+                completeness: number;
+                accuracy?: {
+                    source: string;
+                    threshold: number;
+                } | undefined;
+            } | undefined;
+            readonly conditionalRequired?: {
+                dialect: "cel" | "js" | "cron" | "template";
+                source?: string | undefined;
+                ast?: unknown;
+                meta?: {
+                    rationale?: string | undefined;
+                    generatedBy?: string | undefined;
+                } | undefined;
+            } | undefined;
+            readonly hidden?: boolean | undefined;
+            readonly sortable?: boolean | undefined;
+            readonly inlineHelpText?: string | undefined;
+            readonly trackFeedHistory?: boolean | undefined;
+            readonly caseSensitive?: boolean | undefined;
+            readonly autonumberFormat?: string | undefined;
+            readonly index?: boolean | undefined;
+            readonly type: "number";
+        };
+        /**
+         * Parent `sys_metadata.id` at insertion time (plain text, no FK).
+         * Null for events whose parent row no longer exists (e.g. some
+         * delete records). Forensic only — joins should go through
+         * `(organization_id, type, name)`.
+         */
         readonly metadata_id: {
             readonly readonly?: boolean | undefined;
             readonly format?: string | undefined;
@@ -5667,7 +5885,7 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly maxLength?: number | undefined;
             readonly minLength?: number | undefined;
             readonly scale?: number | undefined;
-            reference: string;
+            readonly reference?: string | undefined;
             readonly referenceFilters?: string[] | undefined;
             readonly writeRequiresMasterRead?: boolean | undefined;
             readonly deleteBehavior?: "set_null" | "cascade" | "restrict" | undefined;
@@ -5794,7 +6012,7 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly caseSensitive?: boolean | undefined;
             readonly autonumberFormat?: string | undefined;
             readonly index?: boolean | undefined;
-            readonly type: "lookup";
+            readonly type: "text";
         };
         /** Machine name (denormalized for easier querying) */
         readonly name: {
@@ -6148,7 +6366,7 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly index?: boolean | undefined;
             readonly type: "text";
         };
-        /** Version number at this snapshot */
+        /** Per-(org,type,name) lineage counter at this snapshot. */
         readonly version: {
             readonly readonly?: boolean | undefined;
             readonly format?: string | undefined;
@@ -6500,7 +6718,10 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly index?: boolean | undefined;
             readonly type: "select";
         };
-        /** Historical metadata snapshot (JSON payload) */
+        /**
+         * Historical metadata snapshot (JSON payload).
+         * Null for `operation_type = 'delete'` — the row carries no body.
+         */
         readonly metadata: {
             readonly readonly?: boolean | undefined;
             readonly format?: string | undefined;
@@ -6676,7 +6897,7 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly index?: boolean | undefined;
             readonly type: "textarea";
         };
-        /** SHA-256 checksum of metadata content */
+        /** SHA-256 checksum of metadata content (null for deletes). */
         readonly checksum: {
             readonly readonly?: boolean | undefined;
             readonly format?: string | undefined;
@@ -6852,7 +7073,7 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly index?: boolean | undefined;
             readonly type: "text";
         };
-        /** Checksum of the previous version */
+        /** Checksum of the previous version (null for the first event). */
         readonly previous_checksum: {
             readonly readonly?: boolean | undefined;
             readonly format?: string | undefined;
@@ -7028,7 +7249,7 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly index?: boolean | undefined;
             readonly type: "text";
         };
-        /** Human-readable description of changes */
+        /** Human-readable description of changes (= MetadataEvent.message). */
         readonly change_note: {
             readonly readonly?: boolean | undefined;
             readonly format?: string | undefined;
@@ -7204,8 +7425,12 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly index?: boolean | undefined;
             readonly type: "textarea";
         };
-        /** Organization ID for multi-tenant isolation */
-        readonly organization_id: {
+        /**
+         * Producer of the event ('sys-metadata-repo', 'fs', 'studio',
+         * 'api', …). Defaults to 'sys-metadata-repo' on the canonical
+         * write path; preserved on history() reads as MetadataEvent.source.
+         */
+        readonly source: {
             readonly readonly?: boolean | undefined;
             readonly format?: string | undefined;
             readonly options?: {
@@ -7251,7 +7476,7 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly maxLength?: number | undefined;
             readonly minLength?: number | undefined;
             readonly scale?: number | undefined;
-            reference: string;
+            readonly reference?: string | undefined;
             readonly referenceFilters?: string[] | undefined;
             readonly writeRequiresMasterRead?: boolean | undefined;
             readonly deleteBehavior?: "set_null" | "cascade" | "restrict" | undefined;
@@ -7378,10 +7603,10 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly caseSensitive?: boolean | undefined;
             readonly autonumberFormat?: string | undefined;
             readonly index?: boolean | undefined;
-            readonly type: "lookup";
+            readonly type: "text";
         };
-        /** Environment ID — null = platform-global, set = env-scoped */
-        readonly project_id: {
+        /** Organization ID for multi-tenant isolation */
+        readonly organization_id: {
             readonly readonly?: boolean | undefined;
             readonly format?: string | undefined;
             readonly options?: {
@@ -7427,7 +7652,7 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly maxLength?: number | undefined;
             readonly minLength?: number | undefined;
             readonly scale?: number | undefined;
-            readonly reference?: string | undefined;
+            reference: string;
             readonly referenceFilters?: string[] | undefined;
             readonly writeRequiresMasterRead?: boolean | undefined;
             readonly deleteBehavior?: "set_null" | "cascade" | "restrict" | undefined;
@@ -7554,9 +7779,9 @@ declare const SysMetadataHistoryObject: Omit<{
             readonly caseSensitive?: boolean | undefined;
             readonly autonumberFormat?: string | undefined;
             readonly index?: boolean | undefined;
-            readonly type: "text";
+            readonly type: "lookup";
         };
-        /** User who made this change */
+        /** User who made this change (= MetadataEvent.actor). */
         readonly recorded_by: {
             readonly readonly?: boolean | undefined;
             readonly format?: string | undefined;
@@ -7910,20 +8135,19 @@ declare const SysMetadataHistoryObject: Omit<{
         };
     };
     readonly indexes: [{
-        readonly fields: ["metadata_id", "version"];
+        readonly fields: ["organization_id", "event_seq"];
+        readonly unique: true;
+    }, {
+        readonly fields: ["organization_id", "type", "name", "version"];
         readonly unique: true;
     }, {
-        readonly fields: ["metadata_id", "recorded_at"];
+        readonly fields: ["organization_id", "type", "name", "recorded_at"];
     }, {
         readonly fields: ["type", "name"];
     }, {
         readonly fields: ["recorded_at"];
     }, {
         readonly fields: ["operation_type"];
-    }, {
-        readonly fields: ["organization_id"];
-    }, {
-        readonly fields: ["project_id"];
     }];
     readonly enable: {
         readonly trackHistory: false;

package/dist/metadata/index.js

@@ -125,11 +125,11 @@ var SysMetadataObject = data.ObjectSchema.create({
       required: false,
       defaultValue: 1
     }),
-    /** Content checksum for change detection */
+    /** Content checksum for change detection (e.g. `sha256:<64 hex>` = 71 chars) */
     checksum: data.Field.text({
       label: "Checksum",
       required: false,
-      maxLength: 64
+      maxLength: 71
     }),
     /** Origin of this metadata record */
     source: data.Field.select(["filesystem", "database", "api", "migration"], {
@@ -196,7 +196,7 @@ var SysMetadataHistoryObject = data.ObjectSchema.create({
   icon: "history",
   isSystem: true,
   managedBy: "system",
-  description: "Version history and audit trail for metadata changes",
+  description: "Durable event log of metadata overlay changes (per-org, append-only)",
   fields: {
     /** Primary Key (UUID) */
     id: data.Field.text({
@@ -204,11 +204,24 @@ var SysMetadataHistoryObject = data.ObjectSchema.create({
       required: true,
       readonly: true
     }),
-    /** Foreign key to sys_metadata.id */
-    metadata_id: data.Field.lookup("sys_metadata", {
-      label: "Metadata",
+    /** Per-org monotonic event sequence (durable cursor for replay). */
+    event_seq: data.Field.number({
+      label: "Event Seq",
       required: true,
-      readonly: true
+      readonly: true,
+      description: "Per-organization monotonic event log cursor."
+    }),
+    /**
+     * Parent `sys_metadata.id` at insertion time (plain text, no FK).
+     * Null for events whose parent row no longer exists (e.g. some
+     * delete records). Forensic only — joins should go through
+     * `(organization_id, type, name)`.
+     */
+    metadata_id: data.Field.text({
+      label: "Metadata ID",
+      required: false,
+      readonly: true,
+      maxLength: 64
     }),
     /** Machine name (denormalized for easier querying) */
     name: data.Field.text({
@@ -226,7 +239,7 @@ var SysMetadataHistoryObject = data.ObjectSchema.create({
       readonly: true,
       maxLength: 100
     }),
-    /** Version number at this snapshot */
+    /** Per-(org,type,name) lineage counter at this snapshot. */
     version: data.Field.number({
       label: "Version",
       required: true,
@@ -238,33 +251,47 @@ var SysMetadataHistoryObject = data.ObjectSchema.create({
       required: true,
       readonly: true
     }),
-    /** Historical metadata snapshot (JSON payload) */
+    /**
+     * Historical metadata snapshot (JSON payload).
+     * Null for `operation_type = 'delete'` — the row carries no body.
+     */
     metadata: data.Field.textarea({
       label: "Metadata",
-      required: true,
+      required: false,
       readonly: true,
-      description: "JSON-serialized metadata snapshot at this version"
+      description: "JSON-serialized metadata snapshot at this version (null for deletes)."
     }),
-    /** SHA-256 checksum of metadata content */
+    /** SHA-256 checksum of metadata content (null for deletes). */
     checksum: data.Field.text({
       label: "Checksum",
-      required: true,
+      required: false,
       readonly: true,
-      maxLength: 64
+      maxLength: 80
     }),
-    /** Checksum of the previous version */
+    /** Checksum of the previous version (null for the first event). */
     previous_checksum: data.Field.text({
       label: "Previous Checksum",
       required: false,
       readonly: true,
-      maxLength: 64
+      maxLength: 80
     }),
-    /** Human-readable description of changes */
+    /** Human-readable description of changes (= MetadataEvent.message). */
     change_note: data.Field.textarea({
       label: "Change Note",
       required: false,
       readonly: true,
-      description: "Description of what changed in this version"
+      description: "Description of what changed in this version."
+    }),
+    /**
+     * Producer of the event ('sys-metadata-repo', 'fs', 'studio',
+     * 'api', …). Defaults to 'sys-metadata-repo' on the canonical
+     * write path; preserved on history() reads as MetadataEvent.source.
+     */
+    source: data.Field.text({
+      label: "Source",
+      required: false,
+      readonly: true,
+      maxLength: 64
     }),
     /** Organization ID for multi-tenant isolation */
     organization_id: data.Field.lookup("sys_organization", {
@@ -273,15 +300,7 @@ var SysMetadataHistoryObject = data.ObjectSchema.create({
       readonly: true,
       description: "Organization for multi-tenant isolation."
     }),
-    /** Environment ID — null = platform-global, set = env-scoped */
-    project_id: data.Field.text({
-      label: "Environment ID",
-      required: false,
-      readonly: true,
-      maxLength: 255,
-      description: "Scopes this history entry to a specific environment."
-    }),
-    /** User who made this change */
+    /** User who made this change (= MetadataEvent.actor). */
     recorded_by: data.Field.lookup("sys_user", {
       label: "Recorded By",
       required: false,
@@ -295,21 +314,18 @@ var SysMetadataHistoryObject = data.ObjectSchema.create({
     })
   },
   indexes: [
-    { fields: ["metadata_id", "version"], unique: true },
-    { fields: ["metadata_id", "recorded_at"] },
+    { fields: ["organization_id", "event_seq"], unique: true },
+    { fields: ["organization_id", "type", "name", "version"], unique: true },
+    { fields: ["organization_id", "type", "name", "recorded_at"] },
     { fields: ["type", "name"] },
     { fields: ["recorded_at"] },
-    { fields: ["operation_type"] },
-    { fields: ["organization_id"] },
-    { fields: ["project_id"] }
+    { fields: ["operation_type"] }
   ],
   enable: {
     trackHistory: false,
-    // Don't track history of history records
     searchable: false,
     apiEnabled: true,
     apiMethods: ["get", "list"],
-    // Read-only via API
     trash: false
   }
 });