@objectstack/objectql 7.3.0 → 7.4.0

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import * as _objectstack_metadata_core from '@objectstack/metadata-core';
 import { MetadataRepository, MetaRef, MetadataItem, PutOptions, PutResult, DeleteOptions, DeleteResult, MetadataWriteIntent, ListFilter, MetadataItemHeader, HistoryOptions, MetadataEvent, WatchFilter } from '@objectstack/metadata-core';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
-import { IFeedService, IRealtimeService } from '@objectstack/spec/contracts';
+import { IFeedService, IRealtimeService, ICryptoProvider } from '@objectstack/spec/contracts';
 
 /**
  * Reserved namespaces that do not get FQN prefix applied.
@@ -138,6 +138,14 @@ declare class SchemaRegistry {
     private namespaceRegistry;
     /** Type → Name/ID → MetadataItem */
     private metadata;
+    /**
+     * App name → navigation contributions (ADR-0029 D7).
+     *
+     * Lets packages inject nav items into apps they do not own (the UI analog
+     * of object extenders). Merged into the owning app's `navigation` tree on
+     * read in {@link getApp} / {@link getAllApps} by group id + priority.
+     */
+    private appNavContributions;
     /**
      * Package ids that must be installed in a DISABLED state. Seeded once at
      * boot (from persisted state) BEFORE any package registration so that every
@@ -215,6 +223,25 @@ declare class SchemaRegistry {
      * Get the owner contributor for an object.
      */
     getObjectOwner(fqn: string): ObjectContributor | undefined;
+    /**
+     * ADR-0029 K0 — assert every registered object resolves to exactly one
+     * owner.
+     *
+     * A second `own` from a different package is already rejected eagerly in
+     * {@link registerObject} (it throws). This is the install-time backstop
+     * called once all packages are registered (kernel bootstrap complete),
+     * and it additionally catches the case `registerObject` cannot: an object
+     * that has only `extend` contributions and **no owner** — which would
+     * otherwise resolve to nothing. Surfacing it here turns a silent
+     * "extend a non-existent object" into a clear bootstrap error.
+     *
+     * This is the invariant the kernel-decomposition (ADR-0029) relies on:
+     * the `sys` namespace is shared across many first-party plugins, but each
+     * object name has exactly one owner.
+     *
+     * @throws Error listing every object whose owner count is not exactly 1.
+     */
+    assertSingleOwnerPerObject(): void;
     /**
      * Unregister all objects contributed by a package.
      *
@@ -259,6 +286,41 @@ declare class SchemaRegistry {
     registerApp(app: any, packageId?: string): void;
     getApp(name: string): any;
     getAllApps(): any[];
+    /**
+     * Register a navigation contribution — a package injecting nav items into
+     * an app it does not own (the UI-layer analog of object `extend`).
+     *
+     * Contributions are merged into the target app's `navigation` tree lazily
+     * on read ({@link getApp} / {@link getAllApps}) by group id + priority, so
+     * registration order does not matter and the owning app can be registered
+     * before or after its contributors.
+     */
+    registerAppNavContribution(contribution: {
+        app: string;
+        group?: string;
+        priority?: number;
+        items?: any[];
+    }, packageId?: string): void;
+    /** Contributions registered for an app (empty array when none). */
+    getAppNavContributions(appName: string): Array<{
+        packageId?: string;
+        group?: string;
+        priority: number;
+        items: any[];
+    }>;
+    /**
+     * Return a copy of `app` with all registered navigation contributions
+     * merged into its `navigation` tree. The stored app is never mutated, so
+     * repeated reads stay idempotent.
+     *
+     * Public so the protocol serving path (`getMetaItems` / `getMetaItem` for
+     * `app`) can merge contributions the same way `getApp` / `getAllApps` do —
+     * the REST app endpoints read through the protocol, not these helpers, so
+     * the merge must be reachable from there too (ADR-0029 D7).
+     */
+    applyNavContributions(app: any): any;
+    /** Depth-first search for a `type: 'group'` nav item by id. */
+    private findNavGroup;
     registerPlugin(manifest: ObjectStackManifest): void;
     getAllPlugins(): ObjectStackManifest[];
     registerKind(kind: {
@@ -386,13 +448,100 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     getMetaTypes(): Promise<{
         types: string[];
         entries: {
+            actions?: {
+                name: string;
+                label: string;
+                type: "url" | "flow" | "script" | "api" | "form" | "modal";
+                refreshAfter: boolean;
+                objectName?: string | undefined;
+                icon?: string | undefined;
+                locations?: ("list_toolbar" | "list_item" | "record_header" | "record_more" | "record_related" | "record_section" | "global_nav")[] | undefined;
+                component?: "action:button" | "action:icon" | "action:menu" | "action:group" | undefined;
+                target?: string | undefined;
+                body?: {
+                    language: "expression";
+                    source: string;
+                } | {
+                    language: "js";
+                    source: string;
+                    capabilities: ("log" | "api.read" | "api.write" | "crypto.uuid" | "crypto.hash")[];
+                    timeoutMs?: number | undefined;
+                    memoryMb?: number | undefined;
+                } | undefined;
+                execute?: string | undefined;
+                params?: {
+                    required: boolean;
+                    name?: string | undefined;
+                    field?: string | undefined;
+                    objectOverride?: string | undefined;
+                    label?: string | undefined;
+                    type?: "number" | "boolean" | "date" | "record" | "file" | "code" | "json" | "url" | "summary" | "datetime" | "color" | "time" | "text" | "textarea" | "email" | "phone" | "password" | "secret" | "markdown" | "html" | "richtext" | "currency" | "percent" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "autonumber" | "composite" | "repeater" | "location" | "address" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "tags" | "vector" | undefined;
+                    options?: {
+                        label: string;
+                        value: string;
+                    }[] | undefined;
+                    placeholder?: string | undefined;
+                    helpText?: string | undefined;
+                    defaultValue?: unknown;
+                    defaultFromRow?: boolean | undefined;
+                }[] | undefined;
+                variant?: "link" | "primary" | "secondary" | "danger" | "ghost" | undefined;
+                confirmText?: string | undefined;
+                successMessage?: string | undefined;
+                resultDialog?: {
+                    title?: string | undefined;
+                    description?: string | undefined;
+                    acknowledge?: string | undefined;
+                    format?: "json" | "text" | "secret" | "qrcode" | "code-list" | undefined;
+                    fields?: {
+                        path: string;
+                        label?: string | undefined;
+                        format?: "json" | "text" | "secret" | "qrcode" | "code-list" | undefined;
+                    }[] | undefined;
+                } | undefined;
+                visible?: {
+                    dialect: "cron" | "cel" | "js" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | undefined;
+                disabled?: boolean | {
+                    dialect: "cron" | "cel" | "js" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | undefined;
+                shortcut?: string | undefined;
+                bulkEnabled?: boolean | undefined;
+                aiExposed?: boolean | undefined;
+                recordIdParam?: string | undefined;
+                recordIdField?: string | undefined;
+                bodyShape?: "flat" | {
+                    wrap: string;
+                } | undefined;
+                method?: "POST" | "PUT" | "DELETE" | "PATCH" | undefined;
+                bodyExtra?: Record<string, unknown> | undefined;
+                mode?: "custom" | "create" | "delete" | "edit" | undefined;
+                timeout?: number | undefined;
+                aria?: {
+                    ariaLabel?: string | undefined;
+                    ariaDescribedBy?: string | undefined;
+                    role?: string | undefined;
+                } | undefined;
+            }[] | undefined;
             type: string;
             schemaId: string;
             allowOrgOverride: boolean;
             overrideSource: "env" | "registry";
             schema: Record<string, unknown>;
             form: {
-                type: "split" | "modal" | "drawer" | "simple" | "tabbed" | "wizard";
+                type: "split" | "drawer" | "modal" | "simple" | "tabbed" | "wizard";
                 data?: {
                     provider: "object";
                     object: string;
@@ -423,7 +572,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 sections?: {
                     collapsible: boolean;
                     collapsed: boolean;
-                    columns: 1 | 2 | 3 | 4;
+                    columns: 1 | 2 | 4 | 3;
                     fields: any[];
                     name?: string | undefined;
                     label?: string | undefined;
@@ -449,7 +598,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 groups?: {
                     collapsible: boolean;
                     collapsed: boolean;
-                    columns: 1 | 2 | 3 | 4;
+                    columns: 1 | 2 | 4 | 3;
                     fields: any[];
                     name?: string | undefined;
                     label?: string | undefined;
@@ -705,7 +854,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                     label: string | undefined;
                     required: boolean;
                     readonly: boolean;
-                    type: "number" | "boolean" | "tags" | "date" | "record" | "file" | "code" | "datetime" | "signature" | "progress" | "url" | "text" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "composite" | "repeater" | "location" | "address" | "json" | "color" | "rating" | "slider" | "qrcode" | "vector";
+                    type: "number" | "boolean" | "tags" | "date" | "record" | "file" | "code" | "datetime" | "signature" | "progress" | "url" | "currency" | "percent" | "password" | "secret" | "email" | "time" | "text" | "textarea" | "phone" | "markdown" | "html" | "richtext" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "composite" | "repeater" | "location" | "address" | "json" | "color" | "rating" | "slider" | "qrcode" | "vector";
                     colSpan: number;
                 }[];
             }[];
@@ -861,6 +1010,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         type: string;
         name: string;
         cacheRequest?: MetadataCacheRequest;
+        locale?: string;
     }): Promise<MetadataCacheResponse>;
     batchData(request: {
         object: string;
@@ -1453,12 +1603,14 @@ declare class ObjectQL implements IDataEngine {
     private logger;
     private datasourceMapping;
     private manifests;
+    private datasourceDefs;
     private hooks;
     private middlewares;
     private actions;
     private functions;
     private hostContext;
     private realtimeService?;
+    private cryptoProvider?;
     private _registry;
     constructor(hostContext?: Record<string, any>);
     /**
@@ -1656,6 +1808,31 @@ declare class ObjectQL implements IDataEngine {
      * Register a new storage driver
      */
     registerDriver(driver: DriverInterface, isDefault?: boolean): void;
+    /**
+     * Register a Datasource *definition* (ADR-0015).
+     *
+     * Distinct from {@link registerDriver}, which registers a live connection.
+     * This captures the declarative `schemaMode` + `external.allowWrites` so the
+     * write gate ({@link assertWriteAllowed}) can enforce external-datasource
+     * ownership. Safe to call repeatedly; last write wins.
+     */
+    registerDatasourceDef(def: {
+        name: string;
+        schemaMode?: string;
+        external?: {
+            allowWrites?: boolean;
+        };
+    }): void;
+    /**
+     * Write gate — Gate 3 of ADR-0015 §5.3.
+     *
+     * Blocks insert/update/delete against a federated datasource
+     * (`schemaMode !== 'managed'`) unless BOTH the datasource opts in
+     * (`external.allowWrites`) AND the object opts in (`external.writable`).
+     * Managed datasources (the common case, including the absence of any
+     * definition) are unaffected.
+     */
+    private assertWriteAllowed;
     /**
      * Set the realtime service for publishing data change events.
      * Should be called after kernel resolves the realtime service.
@@ -1663,6 +1840,54 @@ declare class ObjectQL implements IDataEngine {
      * @param service - An IRealtimeService instance for event publishing
      */
     setRealtimeService(service: IRealtimeService): void;
+    /**
+     * Register the crypto provider that backs `secret`-typed fields.
+     *
+     * When set, the engine encrypts secret fields on write (storing ciphertext in
+     * `sys_secret` and only an opaque ref on the business row) and masks them on
+     * read. When NOT set, writing to an object that declares a secret field is
+     * **fail-closed** — the write throws rather than persist cleartext.
+     *
+     * Mirrors the Settings subsystem's ICryptoProvider wiring; the host (e.g.
+     * `serve`) injects `InMemoryCryptoProvider` in dev and a KMS/Vault-backed
+     * provider in production.
+     */
+    setCryptoProvider(provider: ICryptoProvider): void;
+    /**
+     * Encrypt any `secret`-typed fields on `row` in place before it reaches the
+     * driver. Each plaintext is wrapped by the ICryptoProvider, persisted as a
+     * `sys_secret` row, and replaced on `row` by an opaque ref. Cleartext never
+     * reaches the business table.
+     *
+     * Rules:
+     *  - No secret fields on the object ⇒ no-op (fast path, no crypto cost).
+     *  - `null`/`undefined` value ⇒ left as-is (clears the secret).
+     *  - Value already a ref (re-save of an unchanged ref) ⇒ left as-is.
+     *  - Value equal to the read mask ⇒ dropped, so a form round-trip that
+     *    echoes the mask does not overwrite the stored secret.
+     *  - **Fail-closed:** any other value with no CryptoProvider registered, or
+     *    no reachable `sys_secret` store, THROWS — never persists cleartext.
+     */
+    private encryptSecretFields;
+    /**
+     * Mask `secret`-typed fields on read so plaintext never leaves the engine
+     * through the normal query path. A set secret becomes {@link SECRET_MASK};
+     * an unset one stays `null`. Privileged callers that genuinely need the
+     * plaintext use {@link resolveSecret} against the stored ref.
+     */
+    private maskSecretFields;
+    /**
+     * Dereference a stored secret ref back to its plaintext. Intended for
+     * privileged, server-side consumers (e.g. a datasource connection-pool
+     * binder) — NOT exposed through the generic read path, which only ever
+     * returns the mask.
+     *
+     * Fail-closed: throws when no CryptoProvider is registered or the
+     * `sys_secret` row is missing. Returns `null` when `ref` is not a secret ref.
+     */
+    resolveSecret(ref: unknown, opts?: {
+        tenantId?: string;
+    }): Promise<string | null>;
     /**
      * Helper to get object definition
      */
@@ -1798,6 +2023,17 @@ declare class ObjectQL implements IDataEngine {
      * this method directly looks up a driver by its registered name.
      */
     getDriverByName(name: string): DriverInterface | undefined;
+    /**
+     * Introspect a datasource's live remote schema (ADR-0015).
+     *
+     * Resolves the driver registered under `datasource` and delegates to its
+     * `introspectSchema()` capability. Used by the external-datasource service
+     * (and CLI/REST) to list remote tables and validate federated objects.
+     *
+     * @throws if the datasource has no registered driver, or the driver does
+     *   not support introspection.
+     */
+    introspectDatasource(datasource: string): Promise<unknown>;
     /**
      * Get the driver responsible for the given object.
      *
@@ -2143,7 +2379,7 @@ declare function wrapDeclarativeHook(meta: Hook, handler: HookHandler, opts?: Wr
 
 interface FieldValidationError {
     field: string;
-    code: 'required' | 'min_length' | 'max_length' | 'min_value' | 'max_value' | 'invalid_email' | 'invalid_url' | 'invalid_phone' | 'invalid_number' | 'invalid_boolean' | 'invalid_date' | 'invalid_option';
+    code: 'required' | 'min_length' | 'max_length' | 'min_value' | 'max_value' | 'invalid_email' | 'invalid_url' | 'invalid_phone' | 'invalid_number' | 'invalid_boolean' | 'invalid_date' | 'invalid_option' | 'invalid_transition' | 'rule_violation';
     message: string;
     /** Allowed values for select/multiselect, when applicable. */
     options?: string[];
@@ -2153,7 +2389,7 @@ declare class ValidationError extends Error {
     readonly fields: FieldValidationError[];
     constructor(fields: FieldValidationError[]);
 }
-type Mode = 'insert' | 'update';
+type Mode$1 = 'insert' | 'update';
 interface FieldDef {
     name?: string;
     type: string;
@@ -2179,7 +2415,45 @@ interface FieldDef {
  */
 declare function validateRecord(objectSchema: {
     fields?: Record<string, FieldDef>;
-} | undefined | null, data: Record<string, unknown> | undefined | null, mode: Mode): void;
+} | undefined | null, data: Record<string, unknown> | undefined | null, mode: Mode$1): void;
+
+type Mode = 'insert' | 'update';
+interface EvaluateRulesOptions {
+    /** Prior persisted record (update only). Absent on insert. */
+    previous?: Record<string, unknown> | null;
+    /** Optional logger for non-blocking diagnostics (broken rules, warnings). */
+    logger?: {
+        warn?: (msg: string, meta?: any) => void;
+    };
+}
+/**
+ * Returns true when the object declares at least one validation rule whose
+ * correct evaluation needs the prior record (so the engine knows whether the
+ * extra fetch on the update path is worth it).
+ */
+declare function needsPriorRecord(objectSchema: {
+    validations?: unknown[];
+} | undefined | null): boolean;
+/**
+ * Evaluate an object's declared validation rules against an incoming write.
+ *
+ * Throws `ValidationError` (the same envelope `validateRecord` uses, so REST
+ * surfaces a single `400 VALIDATION_FAILED`) when one or more `error`-severity
+ * rules are violated. Returns void otherwise.
+ */
+declare function evaluateValidationRules(objectSchema: {
+    validations?: unknown[];
+} | undefined | null, data: Record<string, unknown> | undefined | null, mode: Mode, opts?: EvaluateRulesOptions): void;
+/**
+ * Introspection helper (ADR-0020 D3.3): given an object's schema, a state
+ * field, and a current state, return the legal next states declared by the
+ * matching `state_machine` rule. Returns `null` when no such rule exists (so
+ * callers can distinguish "no FSM governs this field" from "a dead-end state
+ * with zero outgoing transitions", which returns `[]`).
+ */
+declare function legalNextStates(objectSchema: {
+    validations?: unknown[];
+} | undefined | null, field: string, currentState: string): string[] | null;
 
 /**
  * MetadataFacade
@@ -2410,6 +2684,45 @@ interface ObjectQLKernelOptions {
  */
 declare function createObjectQLKernel(options?: ObjectQLKernelOptions): Promise<ObjectKernel>;
 
+/**
+ * Secret-field channel — helpers for the `secret` FieldType.
+ *
+ * A `secret` field (DB password, API key, token) is **reversible**: the engine
+ * encrypts it on write via the registered `ICryptoProvider`, persists the
+ * ciphertext as a `sys_secret` row, and stores only an opaque *ref* on the
+ * business row. On read the ref is masked, never the plaintext. This mirrors
+ * the Settings subsystem (`sys_setting.value_enc → sys_secret.id`), generalized
+ * to object fields.
+ *
+ * Contrast with `password` — a one-way hash owned by the auth subsystem, never
+ * decrypted. The two never share a code path.
+ */
+
+/**
+ * Prefix marking a persisted field value as a `sys_secret` handle ref rather
+ * than cleartext. Chosen to be unambiguous and human-greppable in a DB dump,
+ * while making it obvious that the column holds no plaintext.
+ */
+declare const SECRET_REF_PREFIX = "secret:";
+/**
+ * Value returned in place of a secret field on a normal read. Indicates
+ * "a secret is set" without leaking the handle id or the plaintext. A field
+ * with no stored secret resolves to `null` instead.
+ */
+declare const SECRET_MASK = "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+/** Wrap a `sys_secret` handle id as the opaque ref persisted on the row. */
+declare function makeSecretRef(handleId: string): string;
+/** True when `value` is a secret ref previously produced by {@link makeSecretRef}. */
+declare function isSecretRef(value: unknown): value is string;
+/** Extract the `sys_secret` handle id from a ref, or `null` when not a ref. */
+declare function parseSecretRef(value: unknown): string | null;
+/**
+ * Collect the names of `secret`-typed fields declared on an object schema.
+ * Returns an empty array when the schema has no fields or no secret fields —
+ * callers can fast-path on `length === 0` to skip all crypto work.
+ */
+declare function collectSecretFields(schema: ServiceObject | undefined | null): string[];
+
 /**
  * Column metadata from database introspection.
  */
@@ -2497,4 +2810,4 @@ declare function convertIntrospectedSchemaToObjects(introspectedSchema: Introspe
     skipSystemColumns?: boolean;
 }): ServiceObject[];
 
-export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, noopHookMetricsRecorder, parseFQN, toTitleCase, validateRecord, wrapDeclarativeHook };
+export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type EvaluateRulesOptions, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SECRET_MASK, SECRET_REF_PREFIX, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, collectSecretFields, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, evaluateValidationRules, isSecretRef, legalNextStates, makeSecretRef, needsPriorRecord, noopHookMetricsRecorder, parseFQN, parseSecretRef, toTitleCase, validateRecord, wrapDeclarativeHook };