@objectstack/metadata 3.0.1 → 3.0.3

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/metadata@3.0.1 build /home/runner/work/spec/spec/packages/metadata
+> @objectstack/metadata@3.0.3 build /home/runner/work/spec/spec/packages/metadata
 > tsup --config ../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     43.87 KB
-ESM dist/index.mjs.map 88.95 KB
-ESM ⚡️ Build success in 126ms
-CJS dist/index.js     45.68 KB
-CJS dist/index.js.map 90.92 KB
-CJS ⚡️ Build success in 128ms
+CJS dist/index.js     46.91 KB
+CJS dist/index.js.map 93.62 KB
+CJS ⚡️ Build success in 82ms
+ESM dist/index.mjs     45.10 KB
+ESM dist/index.mjs.map 91.64 KB
+ESM ⚡️ Build success in 93ms
 DTS Build start
-DTS ⚡️ Build success in 12195ms
-DTS dist/index.d.mts 14.80 KB
-DTS dist/index.d.ts  14.80 KB
+DTS ⚡️ Build success in 10467ms
+DTS dist/index.d.mts 15.42 KB
+DTS dist/index.d.ts  15.42 KB

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @objectstack/metadata
 
+## 3.0.3
+
+### Patch Changes
+
+- c7267f6: Patch release for maintenance updates and improvements.
+- Updated dependencies [c7267f6]
+  - @objectstack/spec@3.0.3
+  - @objectstack/core@3.0.3
+  - @objectstack/types@3.0.3
+
+## 3.0.2
+
+### Patch Changes
+
+- Updated dependencies [28985f5]
+  - @objectstack/spec@3.0.2
+  - @objectstack/core@3.0.2
+  - @objectstack/types@3.0.2
+
 ## 3.0.1
 
 ### Patch Changes

package/README.md

@@ -1,13 +1,245 @@
 # @objectstack/metadata
 
-The **Model Definition** layer. It provides classes and utilities for parsing and validating ObjectStack metadata schemas.
+> **Metadata Loading, Persistence & Customization Layer for ObjectStack.**
 
-## Features
+`@objectstack/metadata` is the central service responsible for loading, validating, persisting and watching all metadata definitions (Objects, Views, Flows, Apps, Agents, etc.) in the ObjectStack platform.
 
-- **Schema Loading**: Load metadata from JSON/YAML or TypeScript files.
-- **Reference Resolution**: Resolves cross-object references and inheritance.
-- **Validation**: Strict validation against the Zod schemas in `@objectstack/spec`.
+It implements the **`IMetadataService`** contract from `@objectstack/spec` and acts as the single source of truth that all other packages depend on.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     IMetadataService                        │
+│              (Contract: @objectstack/spec)                   │
+├─────────────────────────────────────────────────────────────┤
+│                     MetadataManager                         │
+│            (Orchestrator: this package)                      │
+│                                                             │
+│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
+│  │  In-Memory   │  │   Overlay    │  │  Type Registry    │  │
+│  │  Registry    │  │   System     │  │  & Dependencies   │  │
+│  └─────────────┘  └──────────────┘  └───────────────────┘  │
+├─────────────────────────────────────────────────────────────┤
+│                      Loader Layer                           │
+│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
+│  │ Filesystem   │  │   Remote     │  │   Memory          │  │
+│  │ Loader       │  │   Loader     │  │   Loader          │  │
+│  │ (files)      │  │   (HTTP)     │  │   (test)          │  │
+│  └─────────────┘  └──────────────┘  └───────────────────┘  │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │ DatabaseLoader (planned — datasource-backed storage) │   │
+│  └──────────────────────────────────────────────────────┘   │
+├─────────────────────────────────────────────────────────────┤
+│                    Serializer Layer                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────────────────────┐  │
+│  │   JSON   │  │   YAML   │  │   TypeScript/JavaScript  │  │
+│  └──────────┘  └──────────┘  └──────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Core Concepts
+
+### 1. Metadata Sources (Three-Scope Model)
+
+ObjectStack adopts a three-scope layered model for metadata:
+
+| Scope      | Storage      | Mutability   | Description                                |
+|:-----------|:-------------|:-------------|:-------------------------------------------|
+| `system`   | Filesystem   | Read-only    | Defined in code, shipped with packages      |
+| `platform` | Database     | Admin-editable | Created/modified by admins via UI          |
+| `user`     | Database     | User-editable  | Personal customizations per user           |
+
+Resolution order: **system** ← merge(**platform**) ← merge(**user**).
+
+### 2. Loaders
+
+Loaders are pluggable data sources that know how to read/write metadata from different backends. Each loader declares a `MetadataLoaderContract` with name, protocol, and capabilities:
+
+| Loader              | Protocol       | Read | Write | Watch | Status       |
+|:--------------------|:---------------|:-----|:------|:------|:-------------|
+| `FilesystemLoader`  | `file:`        | ✅   | ✅    | ✅    | Implemented  |
+| `MemoryLoader`      | `memory:`      | ✅   | ✅    | ❌    | Implemented  |
+| `RemoteLoader`      | `http:`        | ✅   | ✅    | ❌    | Implemented  |
+| `DatabaseLoader`    | `datasource:`  | ✅   | ✅    | ✅    | Planned      |
+
+### 3. Serializers
+
+Serializers convert metadata objects to/from different file formats:
+
+- **JSONSerializer** — `.json` files with optional key sorting
+- **YAMLSerializer** — `.yaml`/`.yml` files (JSON_SCHEMA for security)
+- **TypeScriptSerializer** — `.ts`/`.js` module exports (for `defineObject()`, `defineView()`, etc.)
+
+### 4. Overlay / Customization System
+
+The overlay system enables non-destructive customizations on top of package-delivered (system) metadata, following a delta-based approach (JSON Merge Patch):
+
+- **getOverlay** / **saveOverlay** / **removeOverlay** — manage customization deltas
+- **getEffective** — returns the merged result of base + platform overlay + user overlay
+- Overlays never modify the base definition — they are additive patches
+
+### 5. MetadataManager (IMetadataService Implementation)
+
+The `MetadataManager` is the main orchestrator. It provides:
+
+- **Core CRUD**: `register`, `get`, `list`, `unregister`, `exists`, `listNames`
+- **Convenience**: `getObject`, `listObjects`
+- **Package Management**: `unregisterPackage` — unload all metadata from a package
+- **Query / Search**: `query` with filtering, pagination, sorting by type/scope/state/tags
+- **Bulk Operations**: `bulkRegister`, `bulkUnregister` with error handling
+- **Import / Export**: `exportMetadata`, `importMetadata` with conflict resolution (skip/overwrite/merge)
+- **Validation**: `validate` — structural validation of metadata items
+- **Type Registry**: `getRegisteredTypes`, `getTypeInfo` — discover available metadata types
+- **Dependency Tracking**: `getDependencies`, `getDependents` — cross-reference analysis
+- **Watch / Subscribe**: `watchService` — observe metadata changes in real-time
+- **Loader Delegation**: `load`, `loadMany`, `save` — delegate I/O to registered loaders
+
+### 6. NodeMetadataManager
+
+Extends `MetadataManager` with Node.js-specific capabilities:
+
+- Auto-configures `FilesystemLoader` for local development
+- File watching via **chokidar** for hot-reload during development
+- Detects file add/change/delete events and notifies subscribers
+
+### 7. MetadataPlugin
+
+Integrates with the ObjectStack kernel plugin system:
+
+- Registers as the primary `IMetadataService` provider
+- Auto-loads all metadata types from the filesystem on startup (sorted by `loadOrder`)
+- Supports YAML, JSON, TypeScript, and JavaScript metadata formats
+
+## Metadata Types
+
+The platform supports **26 built-in metadata types** across 6 protocol domains:
+
+| Domain       | Types                                                                       |
+|:-------------|:----------------------------------------------------------------------------|
+| **Data**     | `object`, `field`, `datasource`, `validation`                               |
+| **UI**       | `view`, `app`, `dashboard`, `report`, `action`, `theme`                     |
+| **Automation** | `flow`, `workflow`, `trigger`, `schedule`                                 |
+| **System**   | `manifest`, `translation`, `api`, `permission_set`, `role`, `profile`       |
+| **Security** | `permission_set`, `role`                                                    |
+| **AI**       | `agent`, `rag_pipeline`, `model`, `prompt`, `tool`                          |
+
+Each type has a defined `loadOrder` (dependencies load before dependents), file patterns (e.g. `**/*.object.{ts,json,yaml}`), and overlay support flag.
+
+## Spec Protocol References
+
+This package depends on schemas and contracts defined in `@objectstack/spec`:
+
+| Spec Module                      | What It Defines                                     |
+|:---------------------------------|:----------------------------------------------------|
+| `spec/contracts/metadata-service` | `IMetadataService` — the async service interface   |
+| `spec/kernel/metadata-loader`    | Loader contract, load/save/watch schemas, `MetadataManagerConfig` |
+| `spec/kernel/metadata-plugin`    | Type registry, plugin manifest, capabilities        |
+| `spec/kernel/metadata-customization` | Overlay, merge strategy, customization policy   |
+| `spec/system/metadata-persistence` | `MetadataRecord` — DB persistence envelope        |
+| `spec/data/datasource`           | `DatasourceSchema`, `DriverDefinition`, capabilities |
+| `spec/contracts/data-driver`     | `IDataDriver` — database driver interface           |
+
+## Installation
+
+```bash
+pnpm add @objectstack/metadata
+```
 
 ## Usage
 
-Internal package used by `@objectstack/runtime` to process configuration.
+### Basic (Browser-Compatible)
+
+```typescript
+import { MetadataManager, MemoryLoader } from '@objectstack/metadata';
+
+const manager = new MetadataManager({
+  formats: ['json'],
+  loaders: [new MemoryLoader()],
+});
+
+// Register metadata
+await manager.register('object', 'account', { name: 'account', label: 'Account', fields: {} });
+
+// Retrieve
+const obj = await manager.get('object', 'account');
+
+// Query
+const result = await manager.query({ types: ['object'], search: 'account' });
+```
+
+### Node.js (with Filesystem)
+
+```typescript
+import { NodeMetadataManager, MetadataPlugin } from '@objectstack/metadata/node';
+
+const manager = new NodeMetadataManager({
+  rootDir: './src',
+  formats: ['typescript', 'json', 'yaml'],
+  watch: true,
+});
+
+// Load all objects from filesystem
+const objects = await manager.loadMany('object');
+
+// Watch for changes
+manager.watchService('object', (event) => {
+  console.log(`Object ${event.name} was ${event.type}`);
+});
+```
+
+### With Kernel Plugin
+
+```typescript
+import { MetadataPlugin } from '@objectstack/metadata/node';
+
+const plugin = MetadataPlugin({
+  rootDir: './src',
+  watch: process.env.NODE_ENV === 'development',
+});
+// Register with ObjectStack kernel
+kernel.use(plugin);
+```
+
+## Package Structure
+
+```
+packages/metadata/
+├── src/
+│   ├── index.ts                     # Main exports (browser-compatible)
+│   ├── node.ts                      # Node.js exports (filesystem, watching)
+│   ├── metadata-manager.ts          # MetadataManager (IMetadataService impl)
+│   ├── node-metadata-manager.ts     # NodeMetadataManager (+ file watching)
+│   ├── plugin.ts                    # MetadataPlugin (kernel integration)
+│   ├── loaders/
+│   │   ├── loader-interface.ts      # MetadataLoader contract
+│   │   ├── filesystem-loader.ts     # File I/O with glob, cache, ETag
+│   │   ├── memory-loader.ts         # In-memory store (tests/overrides)
+│   │   └── remote-loader.ts         # HTTP API loader with auth
+│   ├── serializers/
+│   │   ├── serializer-interface.ts  # MetadataSerializer contract
+│   │   ├── json-serializer.ts       # JSON format
+│   │   ├── yaml-serializer.ts       # YAML format
+│   │   └── typescript-serializer.ts # TS/JS module format
+│   └── migration/
+│       ├── index.ts                 # Barrel export
+│       └── executor.ts              # ChangeSet executor (DDL operations)
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+├── README.md                        # This file
+└── ROADMAP.md                       # Development roadmap
+```
+
+## Related Packages
+
+| Package                 | Relationship                                     |
+|:------------------------|:-------------------------------------------------|
+| `@objectstack/spec`     | Protocol definitions (schemas, contracts, types)  |
+| `@objectstack/core`     | Logger, service registry, kernel utilities        |
+| `@objectstack/runtime`  | Uses this package to bootstrap metadata           |
+| `apps/studio`           | Visual metadata editor (consumes IMetadataService)|
+
+## License
+
+Apache-2.0 — see [LICENSE](../../LICENSE) for details.

package/ROADMAP.md

@@ -0,0 +1,223 @@
+# @objectstack/metadata — Roadmap
+
+> Development roadmap for the ObjectStack Metadata Service.
+
+## Current Status (v3.0)
+
+### ✅ Implemented
+
+| Feature                          | Description                                    |
+|:---------------------------------|:-----------------------------------------------|
+| `MetadataManager`                | Core orchestrator implementing `IMetadataService` |
+| `IMetadataService` contract      | Full async service interface (30+ methods)      |
+| `FilesystemLoader`               | File I/O with glob, caching, ETag, atomic writes |
+| `MemoryLoader`                   | In-memory storage for tests and overrides       |
+| `RemoteLoader`                   | HTTP API loader with Bearer auth                |
+| JSON / YAML / TypeScript serializers | Multi-format metadata serialization          |
+| Overlay system (in-memory)       | Three-scope delta patches (system/platform/user) |
+| Query / Search                   | Filtering, pagination, sorting by type/scope/state |
+| Bulk operations                  | `bulkRegister` / `bulkUnregister` with error handling |
+| Import / Export                  | Portable bundles with conflict resolution       |
+| Type registry                    | 26 built-in metadata types across 6 domains    |
+| Dependency tracking              | Cross-reference analysis between metadata items |
+| Watch / Subscribe                | Real-time change notification via callbacks     |
+| File watching (Node.js)          | Chokidar-based hot-reload for development       |
+| Kernel plugin                    | `MetadataPlugin` for ObjectStack kernel integration |
+| Migration executor               | ChangeSet-based DDL operations                  |
+| Structural validation            | Basic name/type/label validation                |
+
+### 🟡 Partially Implemented
+
+| Feature                | Status                                           |
+|:-----------------------|:-------------------------------------------------|
+| Overlay persistence    | In-memory only — not persisted to database yet   |
+| Migration executor     | `modify_field` and `rename_object` not complete  |
+| Schema-level validation | Basic structural checks only — no Zod schema dispatch |
+
+---
+
+## Phase 1: DatabaseLoader — Datasource-Backed Persistence 🔴
+
+**Goal**: Enable metadata read/write via any configured `IDataDriver`, so that platform-scope and user-scope metadata can be stored in a database.
+
+**Background**: The spec already defines `MetadataManagerConfig.datasource` (referencing a `DatasourceSchema.name`) and `MetadataRecordSchema` (the DB persistence envelope in `metadata-persistence.zod.ts`). The missing piece is the `DatabaseLoader` that bridges `IMetadataService` ↔ `IDataDriver`.
+
+### Tasks
+
+- [ ] **Implement `DatabaseLoader`** (`src/loaders/database-loader.ts`)
+  - Implement `MetadataLoader` interface with protocol `datasource:`
+  - Accept an `IDataDriver` instance (injected at initialization)
+  - Read/write to the `sys_metadata` table (configurable via `MetadataManagerConfig.tableName`)
+  - Map metadata operations to `IDataDriver` CRUD methods (`find`, `findOne`, `create`, `update`, `delete`)
+  - Serialize metadata payload to the `MetadataRecordSchema` envelope
+  - Support multi-tenant isolation via `tenantId` filter
+  - Support optimistic concurrency via `version` field
+  - Support `scope` filtering (system/platform/user)
+  - Implement `list()` with type filtering and pagination
+  - Implement `exists()` and `stat()` via driver queries
+  - Implement `save()` with upsert semantics (create or update)
+  - Declare capabilities: `{ read: true, write: true, watch: false, list: true }`
+
+- [ ] **Integrate DatabaseLoader into MetadataManager**
+  - Auto-configure `DatabaseLoader` when `config.datasource` is set
+  - Resolve datasource → `IDataDriver` via kernel service registry (`driver.{name}`)
+  - Implement fallback strategy: if DB unavailable, fall back to filesystem or memory per config
+  - Loader priority: DatabaseLoader for platform/user scope, FilesystemLoader for system scope
+
+- [ ] **Schema bootstrapping**
+  - Auto-create `sys_metadata` table on first use via `ISchemaDriver.createCollection()`
+  - Define column schema: `id`, `name`, `type`, `namespace`, `scope`, `metadata` (JSON), `state`, `version`, `tenant_id`, audit fields
+  - Support schema migration for future column additions
+
+- [ ] **Tests**
+  - Unit tests with `MemoryLoader` as mock driver
+  - Integration test pattern for DatabaseLoader ↔ IDataDriver
+  - Fallback behavior tests (datasource unavailable → filesystem)
+
+### Spec Dependencies (Already Defined)
+
+| Spec                              | What It Provides                         |
+|:----------------------------------|:-----------------------------------------|
+| `MetadataManagerConfigSchema`     | `datasource`, `tableName`, `fallback` fields |
+| `MetadataRecordSchema`            | DB record envelope with scope, state, version |
+| `MetadataLoaderContractSchema`    | Protocol `datasource:` declaration        |
+| `IDataDriver`                     | `find`, `findOne`, `create`, `update`, `delete` |
+| `ISchemaDriver`                   | `createCollection`, `addColumn` for DDL   |
+| `DatasourceSchema`                | Connection config with pool, SSL, retry   |
+
+---
+
+## Phase 2: Overlay Persistence & UI Metadata Support 🔴
+
+**Goal**: Persist overlay customizations to the database so that admin and user customizations survive restarts, and expose APIs that the Studio UI can consume.
+
+### Tasks
+
+- [ ] **Persist overlays to database**
+  - Store overlays as `MetadataRecord` entries with `scope: 'platform'` or `scope: 'user'`
+  - Use `extends` field to reference the base system metadata
+  - Use `strategy` field ('merge' or 'replace') to control overlay application
+  - Add `managedBy` tracking ('package', 'platform', 'user')
+
+- [ ] **Implement `getEffective()` with database-backed resolution**
+  - Load base (system, from filesystem) → merge platform overlay (from DB) → merge user overlay (from DB)
+  - Cache effective results with invalidation on overlay changes
+  - Support conflict detection when base metadata is upgraded
+
+- [ ] **REST API for metadata CRUD**
+  - `GET /api/metadata/:type` — list metadata items by type
+  - `GET /api/metadata/:type/:name` — get metadata item
+  - `GET /api/metadata/:type/:name/effective` — get merged effective metadata
+  - `PUT /api/metadata/:type/:name` — create/update metadata (platform scope)
+  - `DELETE /api/metadata/:type/:name` — remove metadata
+  - `GET /api/metadata/:type/:name/overlays` — list overlays
+  - `PUT /api/metadata/:type/:name/overlays/:scope` — save overlay
+  - `POST /api/metadata/query` — query with filters, pagination
+  - `POST /api/metadata/import` / `GET /api/metadata/export` — bulk operations
+
+- [ ] **Permission integration**
+  - Scope-based access control: system (read-only), platform (admin), user (self)
+  - Integrate with `IAuthService` for permission checks
+  - Validate `owner` field for user-scope metadata
+
+- [ ] **Watch / Events for database changes**
+  - Implement polling-based change detection for DatabaseLoader
+  - Emit `MetadataWatchEvent` when database records change
+  - Support webhook notifications for external consumers
+
+---
+
+## Phase 3: Schema Validation & Zod Dispatch 🔴
+
+**Goal**: Full schema validation by dispatching to the correct Zod schema based on metadata type.
+
+### Tasks
+
+- [ ] **Zod schema registry**
+  - Map metadata type → Zod schema (e.g., `object` → `ObjectSchema`, `view` → `ViewSchema`)
+  - Register schemas from `@objectstack/spec` automatically
+  - Support plugin-contributed custom type schemas
+
+- [ ] **Enhanced `validate()` method**
+  - Dispatch to the correct Zod schema per metadata type
+  - Return structured errors with path, message, expected/received
+  - Support `strict` mode (reject unknown fields) and `lenient` mode (warn only)
+  - Validate cross-references (e.g., view references a valid object)
+
+- [ ] **Validation on write**
+  - Optionally validate metadata on `register()` and `save()`
+  - Configurable via `MetadataManagerConfig.validation.strict`
+
+---
+
+## Phase 4: Advanced Features 🔴
+
+### 4a. Metadata Versioning & History
+
+- [ ] Track metadata change history in the database
+- [ ] Support `version` field with auto-increment on save
+- [ ] Implement `getHistory(type, name)` to retrieve version timeline
+- [ ] Implement `rollback(type, name, version)` to restore a previous version
+- [ ] Add `checksum` field for change detection
+
+### 4b. Package Upgrade & Three-Way Merge
+
+- [ ] Implement three-way merge when upgrading package-delivered metadata
+  - Base: previous package version
+  - Ours: current platform customizations (overlays)
+  - Theirs: new package version
+- [ ] Merge conflict detection and resolution UI support
+- [ ] Leverage `MergeStrategyConfigSchema` from spec (keep-custom, accept-incoming, three-way-merge)
+
+### 4c. Metadata Sync & Distribution
+
+- [ ] `pull` — download metadata from a remote ObjectStack instance
+- [ ] `push` — upload local metadata to a remote instance
+- [ ] Selective sync by type, namespace, or package
+- [ ] Conflict detection across instances
+
+### 4d. S3/Cloud Loader
+
+- [ ] Implement `S3Loader` for cloud-native metadata storage
+- [ ] Support `s3:` protocol in `MetadataLoaderContract`
+- [ ] Integrate with object storage for large metadata bundles
+
+---
+
+## Phase 5: Performance & Production Readiness 🔴
+
+- [ ] **Caching layer**
+  - Implement TTL-based cache with configurable `maxSize`
+  - Cache invalidation on write/overlay changes
+  - Support distributed cache (Redis) for multi-instance deployments
+- [ ] **Connection pooling**
+  - Reuse `IDataDriver` connections efficiently
+  - Handle connection failures gracefully with retry policy
+- [ ] **Batch loading optimization**
+  - Load multiple types in a single query where possible
+  - Implement DataLoader-style batching for N+1 prevention
+- [ ] **Metrics & observability**
+  - Track load/save latency, cache hit rates, loader usage
+  - Expose metrics via kernel observability contract
+
+---
+
+## Milestone Summary
+
+| Phase | Target  | Description                                   | Status |
+|:------|:--------|:----------------------------------------------|:-------|
+| —     | v3.0    | Core MetadataManager, Filesystem/Memory/Remote | ✅ Done |
+| 1     | v3.1    | DatabaseLoader — datasource-backed persistence | 🔴 Planned |
+| 2     | v3.2    | Overlay persistence, REST API, UI support      | 🔴 Planned |
+| 3     | v3.3    | Schema validation & Zod dispatch               | 🔴 Planned |
+| 4     | v4.0    | Versioning, merge, sync, S3 loader             | 🔴 Planned |
+| 5     | v4.1    | Caching, pooling, observability                | 🔴 Planned |
+
+---
+
+## Related Documents
+
+- [Root ROADMAP](../../ROADMAP.md) — Full platform evolution (v3.0 → v5.0)
+- [Studio ROADMAP](../../apps/studio/ROADMAP.md) — Visual IDE development phases
+- [Metadata Service Protocol](../../content/docs/protocol/objectos/metadata-service.mdx) — Detailed protocol documentation
+- [DX ROADMAP](../../docs/DX_ROADMAP.md) — Developer experience improvements

package/dist/index.d.mts

@@ -195,6 +195,22 @@ declare class MetadataManager implements IMetadataService {
      * Convenience: list all object definitions
      */
     listObjects(): Promise<unknown[]>;
+    /**
+     * Convenience: get a view definition by name
+     */
+    getView(name: string): Promise<unknown | undefined>;
+    /**
+     * Convenience: list view definitions, optionally filtered by object
+     */
+    listViews(object?: string): Promise<unknown[]>;
+    /**
+     * Convenience: get a dashboard definition by name
+     */
+    getDashboard(name: string): Promise<unknown | undefined>;
+    /**
+     * Convenience: list all dashboard definitions
+     */
+    listDashboards(): Promise<unknown[]>;
     /**
      * Unregister all metadata items from a specific package
      */
@@ -238,7 +254,12 @@ declare class MetadataManager implements IMetadataService {
      * Get the effective (merged) metadata after applying all overlays.
      * Resolution order: system ← merge(platform) ← merge(user)
      */
-    getEffective(type: string, name: string): Promise<unknown | undefined>;
+    getEffective(type: string, name: string, context?: {
+        userId?: string;
+        tenantId?: string;
+        roles?: string[];
+        permissions?: string[];
+    }): Promise<unknown | undefined>;
     /**
      * Watch for metadata changes (IMetadataService contract).
      * Returns a handle for unsubscribing.

package/dist/index.d.ts

@@ -195,6 +195,22 @@ declare class MetadataManager implements IMetadataService {
      * Convenience: list all object definitions
      */
     listObjects(): Promise<unknown[]>;
+    /**
+     * Convenience: get a view definition by name
+     */
+    getView(name: string): Promise<unknown | undefined>;
+    /**
+     * Convenience: list view definitions, optionally filtered by object
+     */
+    listViews(object?: string): Promise<unknown[]>;
+    /**
+     * Convenience: get a dashboard definition by name
+     */
+    getDashboard(name: string): Promise<unknown | undefined>;
+    /**
+     * Convenience: list all dashboard definitions
+     */
+    listDashboards(): Promise<unknown[]>;
     /**
      * Unregister all metadata items from a specific package
      */
@@ -238,7 +254,12 @@ declare class MetadataManager implements IMetadataService {
      * Get the effective (merged) metadata after applying all overlays.
      * Resolution order: system ← merge(platform) ← merge(user)
      */
-    getEffective(type: string, name: string): Promise<unknown | undefined>;
+    getEffective(type: string, name: string, context?: {
+        userId?: string;
+        tenantId?: string;
+        roles?: string[];
+        permissions?: string[];
+    }): Promise<unknown | undefined>;
     /**
      * Watch for metadata changes (IMetadataService contract).
      * Returns a handle for unsubscribing.