@objectstack/metadata-core 7.6.0 → 7.8.0

package/dist/index.cjs

@@ -620,6 +620,607 @@ function multiplexWatch(layers, filter, since) {
   };
 }
 
+// src/objects/sys-metadata.object.ts
+var _data = require('@objectstack/spec/data');
+var SysMetadataObject = _data.ObjectSchema.create({
+  name: "sys_metadata",
+  label: "System Metadata",
+  pluralLabel: "System Metadata",
+  icon: "settings",
+  isSystem: true,
+  // managedBy: 'system' — the metadata table backs every other config
+  // object. Writing rows directly here bypasses the typed Zod APIs and
+  // would let an admin inject malformed payloads. The "All Metadata"
+  // menu is therefore a read-only debug surface (Export only); typed
+  // edits flow through the dedicated per-type pages (Approval Process,
+  // Sharing Rule, etc.).
+  managedBy: "system",
+  description: "Stores platform and user-scope metadata records (objects, views, flows, etc.)",
+  fields: {
+    /** Primary Key (UUID) */
+    id: _data.Field.text({
+      label: "ID",
+      required: true,
+      readonly: true
+    }),
+    /** Machine name — unique identifier used in code references */
+    name: _data.Field.text({
+      label: "Name",
+      required: true,
+      searchable: true,
+      maxLength: 255
+    }),
+    /** Metadata type (e.g. "object", "view", "flow") */
+    type: _data.Field.text({
+      label: "Metadata Type",
+      required: true,
+      searchable: true,
+      maxLength: 100
+    }),
+    /** Namespace / module grouping (e.g. "crm", "core") */
+    namespace: _data.Field.text({
+      label: "Namespace",
+      required: false,
+      defaultValue: "default",
+      maxLength: 100
+    }),
+    /** Package that owns/delivered this metadata (legacy string identifier, kept for compat) */
+    package_id: _data.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: _data.Field.lookup("sys_package_version", {
+      label: "Package Version",
+      required: false,
+      description: "Foreign key to sys_package_version (UUID). Null = platform-built-in or env-level override."
+    }),
+    /** Who manages this record: package, platform, or user */
+    managed_by: _data.Field.select(["package", "platform", "user"], {
+      label: "Managed By",
+      required: false
+    }),
+    /** Scope: system (code), platform (admin DB), user (personal DB) */
+    scope: _data.Field.select(["system", "platform", "user"], {
+      label: "Scope",
+      required: true,
+      defaultValue: "platform"
+    }),
+    /** JSON payload — the actual metadata configuration */
+    metadata: _data.Field.textarea({
+      label: "Metadata",
+      required: true,
+      description: "JSON-serialized metadata payload"
+    }),
+    /** Parent metadata name for extension/override */
+    extends: _data.Field.text({
+      label: "Extends",
+      required: false,
+      maxLength: 255
+    }),
+    /** Merge strategy when extending parent metadata */
+    strategy: _data.Field.select(["merge", "replace"], {
+      label: "Strategy",
+      required: false,
+      defaultValue: "merge"
+    }),
+    /** Owner user ID (for user-scope items) */
+    owner: _data.Field.text({
+      label: "Owner",
+      required: false,
+      maxLength: 255
+    }),
+    /** Lifecycle state */
+    state: _data.Field.select(["draft", "active", "archived", "deprecated"], {
+      label: "State",
+      required: false,
+      defaultValue: "active"
+    }),
+    /** Organization ID for multi-tenant isolation */
+    organization_id: _data.Field.lookup("sys_organization", {
+      label: "Organization",
+      required: false,
+      description: "Organization for multi-tenant isolation."
+    }),
+    /**
+     * @deprecated ADR-0005 (revised 2026-05): per-env DBs replace per-project
+     * isolation. `environment_id` is no longer written by saveMetaItem and not
+     * consulted by overlay reads. Kept for legacy rows; new writes leave it
+     * NULL. Will be dropped in a future schema migration.
+     */
+    environment_id: _data.Field.lookup("sys_environment", {
+      label: "Environment (deprecated)",
+      required: false,
+      description: "DEPRECATED. Use organization_id for tenant isolation."
+    }),
+    /** Version number for optimistic concurrency */
+    version: _data.Field.number({
+      label: "Version",
+      required: false,
+      defaultValue: 1
+    }),
+    /** Content checksum for change detection (e.g. `sha256:<64 hex>` = 71 chars) */
+    checksum: _data.Field.text({
+      label: "Checksum",
+      required: false,
+      maxLength: 71
+    }),
+    /** Origin of this metadata record */
+    source: _data.Field.select(["filesystem", "database", "api", "migration"], {
+      label: "Source",
+      required: false
+    }),
+    /** Classification tags (JSON array) */
+    tags: _data.Field.textarea({
+      label: "Tags",
+      required: false,
+      description: "JSON-serialized array of classification tags"
+    }),
+    /** Audit fields */
+    created_by: _data.Field.lookup("sys_user", {
+      label: "Created By",
+      required: false,
+      readonly: true
+    }),
+    created_at: _data.Field.datetime({
+      label: "Created At",
+      required: false,
+      readonly: true
+    }),
+    updated_by: _data.Field.lookup("sys_user", {
+      label: "Updated By",
+      required: false
+    }),
+    updated_at: _data.Field.datetime({
+      label: "Updated At",
+      required: false
+    })
+  },
+  indexes: [
+    // ADR-0005 (revised 2026-05): overlay uniqueness is scoped by
+    // (type, name, organization_id), restricted to active rows so resets
+    // / archived versions don't collide. environment_id is deprecated and
+    // not part of the discriminator. The runtime layer (protocol.ts
+    // ensureOverlayIndex) issues a DROP-then-CREATE migration to
+    // replace any pre-existing legacy composite index in-place.
+    {
+      name: "idx_sys_metadata_overlay_active",
+      fields: ["type", "name", "organization_id"],
+      unique: true,
+      partial: "state = 'active'"
+    },
+    { name: "idx_sys_metadata_org_type", fields: ["organization_id", "type"] },
+    { fields: ["type", "scope"] },
+    { fields: ["package_version_id"] },
+    { fields: ["state"] },
+    { fields: ["namespace"] }
+  ],
+  enable: {
+    trackHistory: true,
+    searchable: false,
+    apiEnabled: true,
+    apiMethods: ["get", "list", "create", "update", "delete"],
+    trash: false
+  },
+  // Named list views — power the Setup App "Data Model" group so admins
+  // can browse object/field metadata in a typed grid instead of the raw
+  // `All Metadata` debug surface. Each entry pre-filters by `type` and
+  // shows the columns that matter for that type. The dedicated visual
+  // designer (objectui's <ObjectManager> / <FieldDesigner>) deep-links
+  // from the row's `Edit in Designer` action; the grid stays useful for
+  // search, audit (state / updated_at) and triage.
+  listViews: {
+    only_objects: {
+      type: "grid",
+      name: "only_objects",
+      label: "Objects",
+      data: { provider: "object", object: "sys_metadata" },
+      columns: ["name", "namespace", "scope", "managed_by", "state", "updated_at"],
+      filter: [{ field: "type", operator: "equals", value: "object" }],
+      sort: [{ field: "name", order: "asc" }],
+      pagination: { pageSize: 50 }
+    },
+    only_fields: {
+      type: "grid",
+      name: "only_fields",
+      label: "Fields",
+      data: { provider: "object", object: "sys_metadata" },
+      columns: ["name", "namespace", "scope", "managed_by", "state", "updated_at"],
+      filter: [{ field: "type", operator: "equals", value: "field" }],
+      sort: [{ field: "name", order: "asc" }],
+      pagination: { pageSize: 50 }
+    },
+    all_metadata: {
+      type: "grid",
+      name: "all_metadata",
+      label: "All",
+      data: { provider: "object", object: "sys_metadata" },
+      columns: ["name", "type", "namespace", "scope", "state", "updated_at"],
+      sort: [{ field: "updated_at", order: "desc" }],
+      pagination: { pageSize: 50 }
+    }
+  }
+});
+
+// src/objects/sys-metadata-history.object.ts
+
+var SysMetadataHistoryObject = _data.ObjectSchema.create({
+  name: "sys_metadata_history",
+  label: "Metadata History",
+  pluralLabel: "Metadata History",
+  icon: "history",
+  isSystem: true,
+  managedBy: "system",
+  description: "Durable event log of metadata overlay changes (per-org, append-only)",
+  fields: {
+    /** Primary Key (UUID) */
+    id: _data.Field.text({
+      label: "ID",
+      required: true,
+      readonly: true
+    }),
+    /** Per-org monotonic event sequence (durable cursor for replay). */
+    event_seq: _data.Field.number({
+      label: "Event Seq",
+      required: true,
+      readonly: true,
+      description: "Per-organization monotonic event log cursor."
+    }),
+    /** Machine name (denormalized for easier querying) */
+    name: _data.Field.text({
+      label: "Name",
+      required: true,
+      searchable: true,
+      readonly: true,
+      maxLength: 255
+    }),
+    /** Metadata type (denormalized for easier querying) */
+    type: _data.Field.text({
+      label: "Metadata Type",
+      required: true,
+      searchable: true,
+      readonly: true,
+      maxLength: 100
+    }),
+    /** Per-(org,type,name) lineage counter at this snapshot. */
+    version: _data.Field.number({
+      label: "Version",
+      required: true,
+      readonly: true
+    }),
+    /** Type of operation that created this history entry */
+    operation_type: _data.Field.select(["create", "update", "publish", "revert", "delete"], {
+      label: "Operation Type",
+      required: true,
+      readonly: true
+    }),
+    /**
+     * Historical metadata snapshot (JSON payload).
+     * Null for `operation_type = 'delete'` — the row carries no body.
+     */
+    metadata: _data.Field.textarea({
+      label: "Metadata",
+      required: false,
+      readonly: true,
+      description: "JSON-serialized metadata snapshot at this version (null for deletes)."
+    }),
+    /** SHA-256 checksum of metadata content (null for deletes). */
+    checksum: _data.Field.text({
+      label: "Checksum",
+      required: false,
+      readonly: true,
+      maxLength: 80
+    }),
+    /** Checksum of the previous version (null for the first event). */
+    previous_checksum: _data.Field.text({
+      label: "Previous Checksum",
+      required: false,
+      readonly: true,
+      maxLength: 80
+    }),
+    /** 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."
+    }),
+    /**
+     * 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", {
+      label: "Organization",
+      required: false,
+      readonly: true,
+      description: "Organization for multi-tenant isolation."
+    }),
+    /** User who made this change (= MetadataEvent.actor). */
+    recorded_by: _data.Field.lookup("sys_user", {
+      label: "Recorded By",
+      required: false,
+      readonly: true
+    }),
+    /** When was this version recorded */
+    recorded_at: _data.Field.datetime({
+      label: "Recorded At",
+      required: true,
+      readonly: true
+    })
+  },
+  indexes: [
+    { fields: ["organization_id", "event_seq"], unique: true },
+    { fields: ["organization_id", "type", "name", "version"], unique: true },
+    { fields: ["organization_id", "type", "name", "recorded_at"] },
+    // ADR-0009: getByHash() lookup — execution-pinned types resolve a
+    // historical body by content hash via this index.
+    { fields: ["organization_id", "type", "name", "checksum"] },
+    { fields: ["type", "name"] },
+    { fields: ["recorded_at"] },
+    { fields: ["operation_type"] }
+  ],
+  enable: {
+    trackHistory: false,
+    searchable: false,
+    apiEnabled: true,
+    apiMethods: ["get", "list"],
+    trash: false
+  }
+});
+
+// src/objects/sys-metadata-audit.object.ts
+
+var SysMetadataAuditObject = _data.ObjectSchema.create({
+  name: "sys_metadata_audit",
+  label: "Metadata Audit",
+  pluralLabel: "Metadata Audit",
+  icon: "shield-check",
+  isSystem: true,
+  managedBy: "append-only",
+  description: "Append-only audit trail of metadata write decisions (ADR-0010).",
+  fields: {
+    /** Primary Key (UUID) */
+    id: _data.Field.text({
+      label: "ID",
+      required: true,
+      readonly: true
+    }),
+    /** When the decision was made (ISO-8601 UTC). */
+    occurred_at: _data.Field.datetime({
+      label: "Occurred At",
+      required: true,
+      readonly: true
+    }),
+    /** Acting principal (user id, system id, or 'system'). */
+    actor: _data.Field.text({
+      label: "Actor",
+      required: true,
+      readonly: true,
+      maxLength: 255,
+      description: 'Acting principal \u2014 user id, system id, or "system".'
+    }),
+    /** Code path that produced the decision (e.g. `protocol.saveMetaItem`). */
+    source: _data.Field.text({
+      label: "Source",
+      required: false,
+      readonly: true,
+      maxLength: 128
+    }),
+    /** Metadata type (singular, e.g. `app`, `object`, `view`). */
+    type: _data.Field.text({
+      label: "Metadata Type",
+      required: true,
+      readonly: true,
+      searchable: true,
+      maxLength: 100
+    }),
+    /** Item machine name. */
+    name: _data.Field.text({
+      label: "Name",
+      required: true,
+      readonly: true,
+      searchable: true,
+      maxLength: 255
+    }),
+    /** Organization for multi-tenant filtering. NULL for env-wide writes. */
+    organization_id: _data.Field.lookup("sys_organization", {
+      label: "Organization",
+      required: false,
+      readonly: true
+    }),
+    /** Operation kind. */
+    operation: _data.Field.select(["save", "publish", "rollback", "delete", "reset"], {
+      label: "Operation",
+      required: true,
+      readonly: true
+    }),
+    /** Decision outcome — allowed, denied (refused), or forced (bypassed via override). */
+    outcome: _data.Field.select(["allowed", "denied", "forced"], {
+      label: "Outcome",
+      required: true,
+      readonly: true
+    }),
+    /**
+     * Machine-readable code for the decision:
+     *  - on `allowed`: `'ok'`
+     *  - on `denied`: `'not_overridable'` | `'not_creatable'` |
+     *    `'item_locked'` | `'invalid_metadata'` | `'destructive_change'` |
+     *    `'metadata_conflict'`
+     *  - on `forced`: `'lock_override'` (Phase 3)
+     */
+    code: _data.Field.text({
+      label: "Code",
+      required: true,
+      readonly: true,
+      maxLength: 64
+    }),
+    /**
+     * Lock state observed at the time of the decision (`none` if the
+     * item carried no `_lock`). Captured even on `allowed` rows so
+     * later compliance queries can see "what was the lock state when
+     * this write succeeded".
+     */
+    lock_state: _data.Field.select(["none", "no-overlay", "no-delete", "full"], {
+      label: "Lock State",
+      required: false,
+      readonly: true
+    }),
+    /** True when the write succeeded by bypassing a lock (Phase 3). */
+    lock_overridden: _data.Field.boolean({
+      label: "Lock Overridden",
+      required: false,
+      readonly: true
+    }),
+    /** Optional request correlation id for tracing. */
+    request_id: _data.Field.text({
+      label: "Request ID",
+      required: false,
+      readonly: true,
+      maxLength: 128
+    }),
+    /** Optional free-form context (e.g. brief diff summary). */
+    note: _data.Field.textarea({
+      label: "Note",
+      required: false,
+      readonly: true
+    })
+  },
+  indexes: [
+    { fields: ["organization_id", "occurred_at"] },
+    { fields: ["type", "name", "occurred_at"] },
+    { fields: ["actor", "occurred_at"] },
+    { fields: ["outcome"] }
+  ],
+  enable: {
+    trackHistory: false,
+    searchable: false,
+    apiEnabled: true,
+    apiMethods: ["get", "list"],
+    trash: false
+  }
+});
+
+// src/objects/sys-view-definition.object.ts
+
+var SysViewDefinitionObject = _data.ObjectSchema.create({
+  name: "sys_view_definition",
+  label: "View Definition",
+  pluralLabel: "View Definitions",
+  icon: "layout-grid",
+  isSystem: true,
+  description: "Runtime-authored view definitions (shared / personal layers). The package layer ships from source.",
+  fields: {
+    /** Primary Key (UUID) */
+    id: _data.Field.text({ label: "ID", required: true, readonly: true }),
+    /**
+     * Globally-unique qualified view id, `<object>.<viewKey>`, matching the
+     * spec `ViewItemSchema.name`. For personal views the runtime may suffix
+     * to keep it unique per owner.
+     */
+    name: _data.Field.text({
+      label: "Name",
+      required: true,
+      searchable: true,
+      maxLength: 255
+    }),
+    /** Bound object — the foreign key used to aggregate views for the switcher. */
+    object: _data.Field.text({
+      label: "Object",
+      required: true,
+      searchable: true,
+      maxLength: 255
+    }),
+    /** Whether `config` is a ListView (list family) or a FormView. */
+    view_kind: _data.Field.select(["list", "form"], {
+      label: "View Kind",
+      required: true,
+      defaultValue: "list"
+    }),
+    /** Display label (plain string; i18n keys also accepted). */
+    label: _data.Field.text({ label: "Label", required: false, maxLength: 255 }),
+    /** Whether this is the object's default view in the switcher. */
+    is_default: _data.Field.boolean({ label: "Is Default", required: false, defaultValue: false }),
+    /** Sort order within the object's switcher / left rail. */
+    view_order: _data.Field.number({ label: "Order", required: false, defaultValue: 0 }),
+    /**
+     * Identity layer. Only `shared` and `personal` are stored at runtime;
+     * `package` views come from source.
+     */
+    scope: _data.Field.select(["shared", "personal"], {
+      label: "Scope",
+      required: true,
+      defaultValue: "personal"
+    }),
+    /** Owner user id — set when scope = personal; null for shared. */
+    owner: _data.Field.text({ label: "Owner", required: false, maxLength: 255 }),
+    /** Hidden from the switcher (per-user / per-org declutter). */
+    hidden: _data.Field.boolean({ label: "Hidden", required: false, defaultValue: false }),
+    /** The ListView / FormView configuration payload. */
+    config: _data.Field.json({
+      label: "Config",
+      required: true,
+      description: "ListView or FormView configuration (matches spec ViewItem.config)."
+    }),
+    /** Organization for multi-tenant isolation. */
+    organization_id: _data.Field.lookup("sys_organization", {
+      label: "Organization",
+      required: false,
+      description: "Organization for multi-tenant isolation."
+    }),
+    /** Lifecycle state. */
+    state: _data.Field.select(["draft", "active", "archived"], {
+      label: "State",
+      required: false,
+      defaultValue: "active"
+    }),
+    /** Audit fields. */
+    created_by: _data.Field.lookup("sys_user", { label: "Created By", required: false, readonly: true }),
+    created_at: _data.Field.datetime({ label: "Created At", required: false, readonly: true }),
+    updated_by: _data.Field.lookup("sys_user", { label: "Updated By", required: false }),
+    updated_at: _data.Field.datetime({ label: "Updated At", required: false })
+  },
+  indexes: [
+    // A given view name is unique per (organization, owner) among active rows —
+    // a shared view (owner NULL) and each user's personal views don't collide.
+    {
+      name: "idx_sys_view_def_active",
+      fields: ["name", "organization_id", "owner"],
+      unique: true,
+      partial: "state = 'active'"
+    },
+    // The switcher query: views for one object within a tenant.
+    { name: "idx_sys_view_def_object", fields: ["organization_id", "object"] },
+    { fields: ["scope"] },
+    { fields: ["owner"] },
+    { fields: ["state"] }
+  ],
+  enable: {
+    trackHistory: true,
+    searchable: false,
+    apiEnabled: true,
+    apiMethods: ["get", "list", "create", "update", "delete"],
+    trash: false
+  }
+});
+
+
+
+
+
+
 
 
 
@@ -637,5 +1238,5 @@ function multiplexWatch(layers, filter, since) {
 
 
 
-exports.BranchError = _chunkF3VZBGKCcjs.BranchError; exports.ConflictError = _chunkF3VZBGKCcjs.ConflictError; exports.InMemoryRepository = InMemoryRepository; exports.LAYER_SOURCE = LAYER_SOURCE; exports.LayeredRepository = LayeredRepository; exports.MetaRefSchema = MetaRefSchema; exports.MetadataCache = MetadataCache; exports.MetadataError = _chunkF3VZBGKCcjs.MetadataError; exports.MetadataEventSchema = MetadataEventSchema; exports.MetadataItemSchema = MetadataItemSchema; exports.MetadataOpSchema = MetadataOpSchema; exports.MetadataTypeSchema = MetadataTypeSchema; exports.NotFoundError = _chunkF3VZBGKCcjs.NotFoundError; exports.SchemaValidationError = _chunkF3VZBGKCcjs.SchemaValidationError; exports.canonicalize = _chunkF3VZBGKCcjs.canonicalize; exports.hashSpec = _chunkF3VZBGKCcjs.hashSpec; exports.refKey = refKey;
+exports.BranchError = _chunkF3VZBGKCcjs.BranchError; exports.ConflictError = _chunkF3VZBGKCcjs.ConflictError; exports.InMemoryRepository = InMemoryRepository; exports.LAYER_SOURCE = LAYER_SOURCE; exports.LayeredRepository = LayeredRepository; exports.MetaRefSchema = MetaRefSchema; exports.MetadataCache = MetadataCache; exports.MetadataError = _chunkF3VZBGKCcjs.MetadataError; exports.MetadataEventSchema = MetadataEventSchema; exports.MetadataItemSchema = MetadataItemSchema; exports.MetadataOpSchema = MetadataOpSchema; exports.MetadataTypeSchema = MetadataTypeSchema; exports.NotFoundError = _chunkF3VZBGKCcjs.NotFoundError; exports.SchemaValidationError = _chunkF3VZBGKCcjs.SchemaValidationError; exports.SysMetadata = SysMetadataObject; exports.SysMetadataAuditObject = SysMetadataAuditObject; exports.SysMetadataHistoryObject = SysMetadataHistoryObject; exports.SysMetadataObject = SysMetadataObject; exports.SysViewDefinitionObject = SysViewDefinitionObject; exports.canonicalize = _chunkF3VZBGKCcjs.canonicalize; exports.hashSpec = _chunkF3VZBGKCcjs.hashSpec; exports.refKey = refKey;
 //# sourceMappingURL=index.cjs.map