@objectstack/spec 6.3.0 → 6.5.0

package/dist/contracts/index.d.mts

@@ -3,7 +3,7 @@ import { Q as QueryAST } from '../query.zod-C-iygIgx.mjs';
 import { z } from 'zod';
 import { u as ObjectSchema } from '../object.zod-rhReSd7V.mjs';
 import { k as FieldSchema } from '../field.zod-Bqhc6_7G.mjs';
-import { S as MetadataQuery, T as MetadataQueryResult, v as MetadataBulkResult, L as MetadataOverlay, _ as MetadataValidationResult, E as MetadataDependency, a0 as ObjectStackManifest, i as DependencyResolutionResult, al as UpgradePlan, ah as UpgradePackageResponse, ab as RollbackPackageResponse, an as UpgradeSnapshot, a2 as PackageArtifact } from '../manifest.zod-ZIjKKFkz.mjs';
+import { U as MetadataQuery, V as MetadataQueryResult, w as MetadataBulkResult, O as MetadataOverlay, a0 as MetadataValidationResult, H as MetadataDependency, a2 as ObjectStackManifest, i as DependencyResolutionResult, an as UpgradePlan, aj as UpgradePackageResponse, ad as RollbackPackageResponse, ap as UpgradeSnapshot, a4 as PackageArtifact, E as ExecutionContext } from '../execution-context.zod-7FfY8UW2.mjs';
 import { am as PackagePublishResult, J as MetadataHistoryQueryOptions, N as MetadataHistoryQueryResult, z as MetadataDiffResult, h as AppTranslationBundle, aG as TranslationCoverageResult, aK as TranslationDiffItem, au as TenantProvisioningRequest, aw as TenantProvisioningResult, ay as TenantProvisioningStatus, as as TenantPlan, l as DeployDiff, ae as MigrationPlan, p as DeployStatus, D as DeployBundle, t as DeployValidationResult, aA as TenantRegion, f as AppManifest, A as AppCompatibilityCheck, d as AppInstallResult } from '../app-install.zod-FLEuRBBE.mjs';
 import { h as FlowParsed } from '../flow.zod-BFCtGdYw.mjs';
 import { i as ExecutionLog } from '../execution.zod-DGGOFfcb.mjs';
@@ -11,6 +11,7 @@ import { ModelMessage, ToolCallPart, TextStreamPart, ToolSet, ToolResultPart } f
 export { AssistantModelMessage, FinishReason, ModelMessage, SystemModelMessage, TextStreamPart, ToolCallPart, ToolModelMessage, ToolResultPart, ToolSet, UserModelMessage } from 'ai';
 import { d as ExportFormat, i as ExportJobStatus, j as ExportJobSummary, g as ExportJobProgress, z as ScheduledExport, e as ExportImportTemplate } from '../export.zod-DXjlPiR2.mjs';
 import { N as NamespaceConflictError, m as InstalledPackage } from '../package-registry.zod--iKeSd9R.mjs';
+import { j as KnowledgeSource, d as KnowledgeDocument, f as KnowledgeHit } from '../knowledge-document.zod-C8B-jI53.mjs';
 import '../filter.zod-DG_Mf2_S.mjs';
 import '../state-machine.zod-BNanU03M.mjs';
 
@@ -2668,6 +2669,45 @@ interface ChatWithToolsOptions extends AIRequestOptions {
      * or `'abort'` to immediately stop the tool call loop.
      */
     onToolError?: (toolCall: ToolCallPart, error: string) => 'continue' | 'abort';
+    /**
+     * Per-call execution context threaded into every tool handler the
+     * loop dispatches. The HTTP route should populate this from
+     * `req.user` (and any conversation/environment headers) so that
+     * built-in data tools forward the actor into ObjectQL's
+     * `ExecutionContext` and row-level security automatically scopes
+     * what the LLM can see or change.
+     *
+     * Optional for backward compatibility — when omitted, tools fall
+     * back to system-level behaviour.
+     */
+    toolExecutionContext?: ToolExecutionContext;
+}
+/**
+ * Per-call execution context threaded into every tool handler invoked
+ * by {@link ChatWithToolsOptions}. Mirrors {@link ExecutionContext}
+ * but is tailored to the AI tool boundary (no transaction handle, no
+ * raw access token — those live on the engine call site).
+ */
+interface ToolExecutionContext {
+    /**
+     * Authenticated end user on whose behalf the LLM is acting.
+     * Built-in tools promote this into the ObjectQL `ExecutionContext`
+     * so RLS engages. Omit for internal/system invocations.
+     */
+    actor?: {
+        id: string;
+        name?: string;
+        roles?: string[];
+        permissions?: string[];
+    };
+    /** Conversation id for trace/HITL correlation. */
+    conversationId?: string;
+    /** Assistant message id that produced the tool call. */
+    messageId?: string;
+    /** Active environment (multi-tenant project) id, if known. */
+    environmentId?: string;
+    /** Distributed-trace id for cross-service correlation. */
+    traceId?: string;
 }
 /**
  * Options for {@link IAIService.generateObject}.
@@ -4296,6 +4336,164 @@ interface IPackageService {
     togglePackage?(packageId: string, enabled: boolean): Promise<InstalledPackage>;
 }
 
+/**
+ * `IKnowledgeAdapter` — plugin-side contract.
+ *
+ * Each backend (RAGFlow, LlamaIndex, Dify, Vectara, an in-memory
+ * cosine adapter, a custom pgvector adapter, …) ships as its own
+ * plugin package and implements this interface. The adapter is then
+ * registered with the host's `IKnowledgeService` via
+ * `registerAdapter(id, this)` during the plugin's `start()` hook.
+ *
+ * The surface is **deliberately minimal**: no chunk strategy, no
+ * embedding configuration, no rerank toggles. Adapters that need
+ * extra knobs expose them via their plugin options object.
+ *
+ * See `content/docs/protocol/knowledge.mdx`.
+ */
+/**
+ * Context passed to every adapter call. Carries the resolved source
+ * (so the adapter can locate its dataset / collection / table) and
+ * optional trace metadata. Adapters MUST treat unknown fields as
+ * forwards-compatible.
+ */
+interface AdapterContext {
+    /** The source these documents belong to. */
+    source: KnowledgeSource;
+    /** Trace id for correlation across logs / metrics. */
+    traceId?: string;
+    /** Caller-supplied free-form diagnostics tag. */
+    reason?: 'event-sync' | 'reindex' | 'manual' | 'tool-call' | (string & {});
+}
+/** Options accepted by `IKnowledgeAdapter.search`. */
+interface AdapterSearchOptions {
+    /** The source the search is scoped to. */
+    source: KnowledgeSource;
+    /** Max hits to return. */
+    topK: number;
+    /** Adapter-specific filter (e.g. `{ status: 'active' }`). */
+    filter?: Record<string, unknown>;
+    /** Trace id for correlation. */
+    traceId?: string;
+}
+/**
+ * Plugin-implemented adapter. **One per backend**. Stateless across
+ * source ids — the source is supplied per-call.
+ */
+interface IKnowledgeAdapter {
+    /** Stable adapter id used in `KnowledgeSource.adapter`. */
+    readonly id: string;
+    /** Insert or replace documents in the adapter's backend. */
+    upsert(docs: KnowledgeDocument[], ctx: AdapterContext): Promise<void>;
+    /** Run a search query. Returns hits sorted by descending score. */
+    search(query: string, opts: AdapterSearchOptions): Promise<KnowledgeHit[]>;
+    /** Remove documents by id. */
+    delete(documentIds: string[], ctx: AdapterContext): Promise<void>;
+    /**
+     * Optional liveness probe. When implemented, used by the service's
+     * health endpoint and Studio "test connection" actions.
+     */
+    healthCheck?(): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+}
+
+/**
+ * `IKnowledgeService` — orchestrator contract consumed by REST,
+ * `service-ai`, Studio, and custom plugins. Implemented by
+ * `@objectstack/service-knowledge`.
+ *
+ * The service routes requests to one of many `IKnowledgeAdapter`
+ * plugins (RAGFlow, LlamaIndex, Dify, …), wraps search results with a
+ * permission-aware filter that uses the caller's `ExecutionContext`,
+ * and drives event-based sync from ObjectQL.
+ *
+ * See `content/docs/protocol/knowledge.mdx` for the architecture
+ * rationale.
+ */
+/** Options accepted by `IKnowledgeService.search`. */
+interface KnowledgeSearchOptions {
+    /**
+     * Restrict the search to the given source ids. When omitted, every
+     * source the caller is allowed to see is queried.
+     */
+    sourceIds?: string[];
+    /** Max number of hits to return. Adapters may cap further. */
+    topK?: number;
+    /** Adapter-specific filter (passed opaquely). */
+    filter?: Record<string, unknown>;
+    /**
+     * Execution context of the caller. **Required** for permission-aware
+     * retrieval: hits whose `sourceRecordId` would be filtered out by
+     * RLS are dropped before being returned. Internal callers may pass
+     * an `isSystem: true` context to bypass — same convention as
+     * `IDataEngine`.
+     */
+    executionContext?: ExecutionContext;
+}
+/** Options accepted by `IKnowledgeService.reindexSource`. */
+interface KnowledgeReindexOptions {
+    /** When `true`, walk the source and count but do not call the adapter. */
+    dryRun?: boolean;
+    /** Cap on number of documents to reindex (mostly for tests / smoke runs). */
+    limit?: number;
+}
+/** Result of a `reindexSource` call. */
+interface KnowledgeReindexResult {
+    /** Number of documents pushed to the adapter (0 when dryRun). */
+    indexed: number;
+    /** Number of documents discovered (always populated). */
+    discovered: number;
+    /** When applicable, the underlying object's short name. */
+    object?: string;
+    /** When `false`, an adapter / source check prevented the run. */
+    ok: boolean;
+    /** Free-form diagnostics. */
+    message?: string;
+}
+/**
+ * Core service contract.
+ *
+ * Every adapter plugin calls `registerAdapter(id, this)` during its
+ * `start()` hook. Sources reference adapters by id; unknown ids cause
+ * `search` / `indexDocument` to throw early with a clear error.
+ */
+interface IKnowledgeService {
+    /** Register (or replace) an adapter under the given id. */
+    registerAdapter(id: string, adapter: IKnowledgeAdapter): void;
+    /** Resolve an adapter by id. Throws when unknown. */
+    getAdapter(id: string): IKnowledgeAdapter;
+    /** Enumerate registered adapter ids. */
+    listAdapters(): string[];
+    /** Register a logical knowledge source. */
+    registerSource(source: KnowledgeSource): void;
+    /** Remove a registered source. Does not delete underlying data. */
+    unregisterSource(sourceId: string): void;
+    /** Snapshot of registered sources (read-only). */
+    listSources(): KnowledgeSource[];
+    /** Look up a single source. Returns `undefined` when not registered. */
+    getSource(sourceId: string): KnowledgeSource | undefined;
+    /** Index (insert or replace) a document into the source's adapter. */
+    indexDocument(sourceId: string, doc: KnowledgeDocument): Promise<void>;
+    /** Remove a document from the source's adapter. */
+    deleteDocument(sourceId: string, documentId: string): Promise<void>;
+    /**
+     * Bulk reindex a source from its declared origin. Object sources
+     * walk the underlying object via `IDataEngine`; file / http sources
+     * delegate to the adapter's own ingestion.
+     */
+    reindexSource(sourceId: string, opts?: KnowledgeReindexOptions): Promise<KnowledgeReindexResult>;
+    /**
+     * Run a search across one or more sources. Results are
+     * permission-filtered before being returned (see
+     * `KnowledgeSearchOptions.executionContext`).
+     */
+    search(query: string, opts?: KnowledgeSearchOptions): Promise<KnowledgeHit[]>;
+}
+/** Canonical service-registry id used by `IKnowledgeService` consumers. */
+declare const KNOWLEDGE_SERVICE: "knowledge";
+
 /**
  * ITursoPlatformService - Turso Platform API Contract
  *
@@ -5103,4 +5301,4 @@ interface IClusterService {
     close(): Promise<void>;
 }
 
-export type { AIConversation, AIMessage, AIMessageWithTools, AIObjectResult, AIRequestOptions, AIRequestOptionsWithTools, AIResult, AIStreamEvent, AIToolCall, AIToolDefinition, AIToolResult, AnalyticsQuery, AnalyticsResult, AnalyticsStrategy, ApprovalActionRow, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalProcessRow, ApprovalRequestRow, ApprovalStatus, AuthResult, AuthSession, AuthUser, AutomationContext, AutomationResult, CacheStats, ChatWithToolsOptions, CheckNamespaceInput, CheckNamespaceResult, ClusterCallContext, CounterIncrOptions, CreateExportJobInput, CreateExportJobResult, CreateFeedItemInput, CreateTursoDatabaseOptions, CryptoContext, CryptoHandle, CubeMeta, DefineApprovalProcessInput, DefineSharingRuleInput, DeployExecutionResult, DriverCapabilities, DriverInterface, EmailAddress, EmailAttachment, EmailDeliveryStatus, ExecuteUpgradeInput, ExportJobDownload, ExportJobListResult, FeedListResult, GenerateObjectOptions, GrantShareInput, GraphQLRequest, GraphQLResponse, HealthStatus, IAIConversationService, IAIService, IAdvancedServiceRegistry, IAnalyticsService, IAppLifecycleService, IApprovalService, IAuthService, IAutomationService, IBasicServiceRegistry, ICacheService, IClusterService, ICounter, ICryptoProvider, IDataDriver, IDataEngine, IDepartmentGraphService, IDeployPipelineService, IEmailService, IEmailTransport, IExportService, IFeedService, IGraphQLService, IHttpRequest, IHttpResponse, IHttpServer, II18nService, IJobService, IKV, ILock, IMetadataService, INotificationService, IPackageService, IPluginLifecycleEvents, IPluginValidator, IProvisioningService, IPubSub, IQueueService, IRealtimeService, IReportService, ISchemaDiffService, ISchemaDriver, ISearchService, ISeedLoaderService, IServiceRegistry, ISharingRuleService, ISharingService, IStartupOrchestrator, IStorageService, ITeamGraphService, ITenantRouter, ITursoPlatformService, ITypedEventEmitter, IUIService, IWorkflowService, InstallPackageInput, InstallPackageResult, IntrospectedColumn, IntrospectedIndex, IntrospectedSchema, IntrospectedTable, JobExecution, JobHandler, JobSchedule, KVEntry, KVSetOptions, LLMAdapter, ListExportJobsOptions, ListFeedOptions, LockAcquireOptions, LockHandle, Logger, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle, Middleware, MigrationApplyResult, NormalizedEmailMessage, NotificationChannel, NotificationMessage, NotificationResult, PendingActionRow, PendingActionStatus, PlanUpgradeInput, Plugin, PluginStartupResult, PresignedDownloadDescriptor, PresignedUploadDescriptor, ProposePendingActionInput, PubSubHandler, PubSubMessage, PublishOptions, QueueBackoffPolicy, QueueHandler, QueueMessage, QueueMessageRecord, QueuePublishOptions, RealtimeEventHandler, RealtimeEventPayload, RealtimeSubscriptionFilter, RealtimeSubscriptionOptions, RecordShare, ReportFormat, ReportQuery, ReportRunResult, ReportSchedule, ResolveDependenciesInput, ResolvedTenantContext, RollbackInput, RouteHandler, SaveReportInput, SavedReport, ScheduleExportInput, ScheduleReportInput, SearchHit, SearchOptions, SearchResult, SendEmailInput, SendEmailResult, SendTemplateInput, ShareAccessLevel, ShareRecipientType, ShareSource, SharingExecutionContext, SharingRuleEvaluationResult, SharingRuleRecipientType, SharingRuleRow, StartupOptions, StorageFileInfo, StorageUploadOptions, StrategyContext, SubmitApprovalInput, SubscribeInput, SubscribeOptions, TransportSendResult, TursoDatabaseInfo, TursoTokenResult, TursoTokenScope, Unsubscribe, UpdateFeedItemInput, UploadArtifactInput, UploadArtifactResult, ValidationResult, WorkflowStatus, WorkflowTransition, WorkflowTransitionResult };
+export { type AIConversation, type AIMessage, type AIMessageWithTools, type AIObjectResult, type AIRequestOptions, type AIRequestOptionsWithTools, type AIResult, type AIStreamEvent, type AIToolCall, type AIToolDefinition, type AIToolResult, type AdapterContext, type AdapterSearchOptions, type AnalyticsQuery, type AnalyticsResult, type AnalyticsStrategy, type ApprovalActionRow, type ApprovalDecisionInput, type ApprovalDecisionResult, type ApprovalProcessRow, type ApprovalRequestRow, type ApprovalStatus, type AuthResult, type AuthSession, type AuthUser, type AutomationContext, type AutomationResult, type CacheStats, type ChatWithToolsOptions, type CheckNamespaceInput, type CheckNamespaceResult, type ClusterCallContext, type CounterIncrOptions, type CreateExportJobInput, type CreateExportJobResult, type CreateFeedItemInput, type CreateTursoDatabaseOptions, type CryptoContext, type CryptoHandle, type CubeMeta, type DefineApprovalProcessInput, type DefineSharingRuleInput, type DeployExecutionResult, type DriverCapabilities, type DriverInterface, type EmailAddress, type EmailAttachment, type EmailDeliveryStatus, type ExecuteUpgradeInput, type ExportJobDownload, type ExportJobListResult, type FeedListResult, type GenerateObjectOptions, type GrantShareInput, type GraphQLRequest, type GraphQLResponse, type HealthStatus, type IAIConversationService, type IAIService, type IAdvancedServiceRegistry, type IAnalyticsService, type IAppLifecycleService, type IApprovalService, type IAuthService, type IAutomationService, type IBasicServiceRegistry, type ICacheService, type IClusterService, type ICounter, type ICryptoProvider, type IDataDriver, type IDataEngine, type IDepartmentGraphService, type IDeployPipelineService, type IEmailService, type IEmailTransport, type IExportService, type IFeedService, type IGraphQLService, type IHttpRequest, type IHttpResponse, type IHttpServer, type II18nService, type IJobService, type IKV, type IKnowledgeAdapter, type IKnowledgeService, type ILock, type IMetadataService, type INotificationService, type IPackageService, type IPluginLifecycleEvents, type IPluginValidator, type IProvisioningService, type IPubSub, type IQueueService, type IRealtimeService, type IReportService, type ISchemaDiffService, type ISchemaDriver, type ISearchService, type ISeedLoaderService, type IServiceRegistry, type ISharingRuleService, type ISharingService, type IStartupOrchestrator, type IStorageService, type ITeamGraphService, type ITenantRouter, type ITursoPlatformService, type ITypedEventEmitter, type IUIService, type IWorkflowService, type InstallPackageInput, type InstallPackageResult, type IntrospectedColumn, type IntrospectedIndex, type IntrospectedSchema, type IntrospectedTable, type JobExecution, type JobHandler, type JobSchedule, KNOWLEDGE_SERVICE, type KVEntry, type KVSetOptions, type KnowledgeReindexOptions, type KnowledgeReindexResult, type KnowledgeSearchOptions, type LLMAdapter, type ListExportJobsOptions, type ListFeedOptions, type LockAcquireOptions, type LockHandle, type Logger, type MetadataExportOptions, type MetadataImportOptions, type MetadataImportResult, type MetadataTypeInfo, type MetadataWatchCallback, type MetadataWatchHandle, type Middleware, type MigrationApplyResult, type NormalizedEmailMessage, type NotificationChannel, type NotificationMessage, type NotificationResult, type PendingActionRow, type PendingActionStatus, type PlanUpgradeInput, type Plugin, type PluginStartupResult, type PresignedDownloadDescriptor, type PresignedUploadDescriptor, type ProposePendingActionInput, type PubSubHandler, type PubSubMessage, type PublishOptions, type QueueBackoffPolicy, type QueueHandler, type QueueMessage, type QueueMessageRecord, type QueuePublishOptions, type RealtimeEventHandler, type RealtimeEventPayload, type RealtimeSubscriptionFilter, type RealtimeSubscriptionOptions, type RecordShare, type ReportFormat, type ReportQuery, type ReportRunResult, type ReportSchedule, type ResolveDependenciesInput, type ResolvedTenantContext, type RollbackInput, type RouteHandler, type SaveReportInput, type SavedReport, type ScheduleExportInput, type ScheduleReportInput, type SearchHit, type SearchOptions, type SearchResult, type SendEmailInput, type SendEmailResult, type SendTemplateInput, type ShareAccessLevel, type ShareRecipientType, type ShareSource, type SharingExecutionContext, type SharingRuleEvaluationResult, type SharingRuleRecipientType, type SharingRuleRow, type StartupOptions, type StorageFileInfo, type StorageUploadOptions, type StrategyContext, type SubmitApprovalInput, type SubscribeInput, type SubscribeOptions, type ToolExecutionContext, type TransportSendResult, type TursoDatabaseInfo, type TursoTokenResult, type TursoTokenScope, type Unsubscribe, type UpdateFeedItemInput, type UploadArtifactInput, type UploadArtifactResult, type ValidationResult, type WorkflowStatus, type WorkflowTransition, type WorkflowTransitionResult };

package/dist/contracts/index.d.ts

@@ -3,7 +3,7 @@ import { Q as QueryAST } from '../query.zod-CGnJOIQH.js';
 import { z } from 'zod';
 import { u as ObjectSchema } from '../object.zod-BntYUReb.js';
 import { k as FieldSchema } from '../field.zod-Bqhc6_7G.js';
-import { S as MetadataQuery, T as MetadataQueryResult, v as MetadataBulkResult, L as MetadataOverlay, _ as MetadataValidationResult, E as MetadataDependency, a0 as ObjectStackManifest, i as DependencyResolutionResult, al as UpgradePlan, ah as UpgradePackageResponse, ab as RollbackPackageResponse, an as UpgradeSnapshot, a2 as PackageArtifact } from '../manifest.zod-ZIjKKFkz.js';
+import { U as MetadataQuery, V as MetadataQueryResult, w as MetadataBulkResult, O as MetadataOverlay, a0 as MetadataValidationResult, H as MetadataDependency, a2 as ObjectStackManifest, i as DependencyResolutionResult, an as UpgradePlan, aj as UpgradePackageResponse, ad as RollbackPackageResponse, ap as UpgradeSnapshot, a4 as PackageArtifact, E as ExecutionContext } from '../execution-context.zod-7FfY8UW2.js';
 import { am as PackagePublishResult, J as MetadataHistoryQueryOptions, N as MetadataHistoryQueryResult, z as MetadataDiffResult, h as AppTranslationBundle, aG as TranslationCoverageResult, aK as TranslationDiffItem, au as TenantProvisioningRequest, aw as TenantProvisioningResult, ay as TenantProvisioningStatus, as as TenantPlan, l as DeployDiff, ae as MigrationPlan, p as DeployStatus, D as DeployBundle, t as DeployValidationResult, aA as TenantRegion, f as AppManifest, A as AppCompatibilityCheck, d as AppInstallResult } from '../app-install.zod-FLEuRBBE.js';
 import { h as FlowParsed } from '../flow.zod-BFCtGdYw.js';
 import { i as ExecutionLog } from '../execution.zod-DGGOFfcb.js';
@@ -11,6 +11,7 @@ import { ModelMessage, ToolCallPart, TextStreamPart, ToolSet, ToolResultPart } f
 export { AssistantModelMessage, FinishReason, ModelMessage, SystemModelMessage, TextStreamPart, ToolCallPart, ToolModelMessage, ToolResultPart, ToolSet, UserModelMessage } from 'ai';
 import { d as ExportFormat, i as ExportJobStatus, j as ExportJobSummary, g as ExportJobProgress, z as ScheduledExport, e as ExportImportTemplate } from '../export.zod-DXjlPiR2.js';
 import { N as NamespaceConflictError, m as InstalledPackage } from '../package-registry.zod--iKeSd9R.js';
+import { j as KnowledgeSource, d as KnowledgeDocument, f as KnowledgeHit } from '../knowledge-document.zod-C8B-jI53.js';
 import '../filter.zod-DG_Mf2_S.js';
 import '../state-machine.zod-BNanU03M.js';
 
@@ -2668,6 +2669,45 @@ interface ChatWithToolsOptions extends AIRequestOptions {
      * or `'abort'` to immediately stop the tool call loop.
      */
     onToolError?: (toolCall: ToolCallPart, error: string) => 'continue' | 'abort';
+    /**
+     * Per-call execution context threaded into every tool handler the
+     * loop dispatches. The HTTP route should populate this from
+     * `req.user` (and any conversation/environment headers) so that
+     * built-in data tools forward the actor into ObjectQL's
+     * `ExecutionContext` and row-level security automatically scopes
+     * what the LLM can see or change.
+     *
+     * Optional for backward compatibility — when omitted, tools fall
+     * back to system-level behaviour.
+     */
+    toolExecutionContext?: ToolExecutionContext;
+}
+/**
+ * Per-call execution context threaded into every tool handler invoked
+ * by {@link ChatWithToolsOptions}. Mirrors {@link ExecutionContext}
+ * but is tailored to the AI tool boundary (no transaction handle, no
+ * raw access token — those live on the engine call site).
+ */
+interface ToolExecutionContext {
+    /**
+     * Authenticated end user on whose behalf the LLM is acting.
+     * Built-in tools promote this into the ObjectQL `ExecutionContext`
+     * so RLS engages. Omit for internal/system invocations.
+     */
+    actor?: {
+        id: string;
+        name?: string;
+        roles?: string[];
+        permissions?: string[];
+    };
+    /** Conversation id for trace/HITL correlation. */
+    conversationId?: string;
+    /** Assistant message id that produced the tool call. */
+    messageId?: string;
+    /** Active environment (multi-tenant project) id, if known. */
+    environmentId?: string;
+    /** Distributed-trace id for cross-service correlation. */
+    traceId?: string;
 }
 /**
  * Options for {@link IAIService.generateObject}.
@@ -4296,6 +4336,164 @@ interface IPackageService {
     togglePackage?(packageId: string, enabled: boolean): Promise<InstalledPackage>;
 }
 
+/**
+ * `IKnowledgeAdapter` — plugin-side contract.
+ *
+ * Each backend (RAGFlow, LlamaIndex, Dify, Vectara, an in-memory
+ * cosine adapter, a custom pgvector adapter, …) ships as its own
+ * plugin package and implements this interface. The adapter is then
+ * registered with the host's `IKnowledgeService` via
+ * `registerAdapter(id, this)` during the plugin's `start()` hook.
+ *
+ * The surface is **deliberately minimal**: no chunk strategy, no
+ * embedding configuration, no rerank toggles. Adapters that need
+ * extra knobs expose them via their plugin options object.
+ *
+ * See `content/docs/protocol/knowledge.mdx`.
+ */
+/**
+ * Context passed to every adapter call. Carries the resolved source
+ * (so the adapter can locate its dataset / collection / table) and
+ * optional trace metadata. Adapters MUST treat unknown fields as
+ * forwards-compatible.
+ */
+interface AdapterContext {
+    /** The source these documents belong to. */
+    source: KnowledgeSource;
+    /** Trace id for correlation across logs / metrics. */
+    traceId?: string;
+    /** Caller-supplied free-form diagnostics tag. */
+    reason?: 'event-sync' | 'reindex' | 'manual' | 'tool-call' | (string & {});
+}
+/** Options accepted by `IKnowledgeAdapter.search`. */
+interface AdapterSearchOptions {
+    /** The source the search is scoped to. */
+    source: KnowledgeSource;
+    /** Max hits to return. */
+    topK: number;
+    /** Adapter-specific filter (e.g. `{ status: 'active' }`). */
+    filter?: Record<string, unknown>;
+    /** Trace id for correlation. */
+    traceId?: string;
+}
+/**
+ * Plugin-implemented adapter. **One per backend**. Stateless across
+ * source ids — the source is supplied per-call.
+ */
+interface IKnowledgeAdapter {
+    /** Stable adapter id used in `KnowledgeSource.adapter`. */
+    readonly id: string;
+    /** Insert or replace documents in the adapter's backend. */
+    upsert(docs: KnowledgeDocument[], ctx: AdapterContext): Promise<void>;
+    /** Run a search query. Returns hits sorted by descending score. */
+    search(query: string, opts: AdapterSearchOptions): Promise<KnowledgeHit[]>;
+    /** Remove documents by id. */
+    delete(documentIds: string[], ctx: AdapterContext): Promise<void>;
+    /**
+     * Optional liveness probe. When implemented, used by the service's
+     * health endpoint and Studio "test connection" actions.
+     */
+    healthCheck?(): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+}
+
+/**
+ * `IKnowledgeService` — orchestrator contract consumed by REST,
+ * `service-ai`, Studio, and custom plugins. Implemented by
+ * `@objectstack/service-knowledge`.
+ *
+ * The service routes requests to one of many `IKnowledgeAdapter`
+ * plugins (RAGFlow, LlamaIndex, Dify, …), wraps search results with a
+ * permission-aware filter that uses the caller's `ExecutionContext`,
+ * and drives event-based sync from ObjectQL.
+ *
+ * See `content/docs/protocol/knowledge.mdx` for the architecture
+ * rationale.
+ */
+/** Options accepted by `IKnowledgeService.search`. */
+interface KnowledgeSearchOptions {
+    /**
+     * Restrict the search to the given source ids. When omitted, every
+     * source the caller is allowed to see is queried.
+     */
+    sourceIds?: string[];
+    /** Max number of hits to return. Adapters may cap further. */
+    topK?: number;
+    /** Adapter-specific filter (passed opaquely). */
+    filter?: Record<string, unknown>;
+    /**
+     * Execution context of the caller. **Required** for permission-aware
+     * retrieval: hits whose `sourceRecordId` would be filtered out by
+     * RLS are dropped before being returned. Internal callers may pass
+     * an `isSystem: true` context to bypass — same convention as
+     * `IDataEngine`.
+     */
+    executionContext?: ExecutionContext;
+}
+/** Options accepted by `IKnowledgeService.reindexSource`. */
+interface KnowledgeReindexOptions {
+    /** When `true`, walk the source and count but do not call the adapter. */
+    dryRun?: boolean;
+    /** Cap on number of documents to reindex (mostly for tests / smoke runs). */
+    limit?: number;
+}
+/** Result of a `reindexSource` call. */
+interface KnowledgeReindexResult {
+    /** Number of documents pushed to the adapter (0 when dryRun). */
+    indexed: number;
+    /** Number of documents discovered (always populated). */
+    discovered: number;
+    /** When applicable, the underlying object's short name. */
+    object?: string;
+    /** When `false`, an adapter / source check prevented the run. */
+    ok: boolean;
+    /** Free-form diagnostics. */
+    message?: string;
+}
+/**
+ * Core service contract.
+ *
+ * Every adapter plugin calls `registerAdapter(id, this)` during its
+ * `start()` hook. Sources reference adapters by id; unknown ids cause
+ * `search` / `indexDocument` to throw early with a clear error.
+ */
+interface IKnowledgeService {
+    /** Register (or replace) an adapter under the given id. */
+    registerAdapter(id: string, adapter: IKnowledgeAdapter): void;
+    /** Resolve an adapter by id. Throws when unknown. */
+    getAdapter(id: string): IKnowledgeAdapter;
+    /** Enumerate registered adapter ids. */
+    listAdapters(): string[];
+    /** Register a logical knowledge source. */
+    registerSource(source: KnowledgeSource): void;
+    /** Remove a registered source. Does not delete underlying data. */
+    unregisterSource(sourceId: string): void;
+    /** Snapshot of registered sources (read-only). */
+    listSources(): KnowledgeSource[];
+    /** Look up a single source. Returns `undefined` when not registered. */
+    getSource(sourceId: string): KnowledgeSource | undefined;
+    /** Index (insert or replace) a document into the source's adapter. */
+    indexDocument(sourceId: string, doc: KnowledgeDocument): Promise<void>;
+    /** Remove a document from the source's adapter. */
+    deleteDocument(sourceId: string, documentId: string): Promise<void>;
+    /**
+     * Bulk reindex a source from its declared origin. Object sources
+     * walk the underlying object via `IDataEngine`; file / http sources
+     * delegate to the adapter's own ingestion.
+     */
+    reindexSource(sourceId: string, opts?: KnowledgeReindexOptions): Promise<KnowledgeReindexResult>;
+    /**
+     * Run a search across one or more sources. Results are
+     * permission-filtered before being returned (see
+     * `KnowledgeSearchOptions.executionContext`).
+     */
+    search(query: string, opts?: KnowledgeSearchOptions): Promise<KnowledgeHit[]>;
+}
+/** Canonical service-registry id used by `IKnowledgeService` consumers. */
+declare const KNOWLEDGE_SERVICE: "knowledge";
+
 /**
  * ITursoPlatformService - Turso Platform API Contract
  *
@@ -5103,4 +5301,4 @@ interface IClusterService {
     close(): Promise<void>;
 }
 
-export type { AIConversation, AIMessage, AIMessageWithTools, AIObjectResult, AIRequestOptions, AIRequestOptionsWithTools, AIResult, AIStreamEvent, AIToolCall, AIToolDefinition, AIToolResult, AnalyticsQuery, AnalyticsResult, AnalyticsStrategy, ApprovalActionRow, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalProcessRow, ApprovalRequestRow, ApprovalStatus, AuthResult, AuthSession, AuthUser, AutomationContext, AutomationResult, CacheStats, ChatWithToolsOptions, CheckNamespaceInput, CheckNamespaceResult, ClusterCallContext, CounterIncrOptions, CreateExportJobInput, CreateExportJobResult, CreateFeedItemInput, CreateTursoDatabaseOptions, CryptoContext, CryptoHandle, CubeMeta, DefineApprovalProcessInput, DefineSharingRuleInput, DeployExecutionResult, DriverCapabilities, DriverInterface, EmailAddress, EmailAttachment, EmailDeliveryStatus, ExecuteUpgradeInput, ExportJobDownload, ExportJobListResult, FeedListResult, GenerateObjectOptions, GrantShareInput, GraphQLRequest, GraphQLResponse, HealthStatus, IAIConversationService, IAIService, IAdvancedServiceRegistry, IAnalyticsService, IAppLifecycleService, IApprovalService, IAuthService, IAutomationService, IBasicServiceRegistry, ICacheService, IClusterService, ICounter, ICryptoProvider, IDataDriver, IDataEngine, IDepartmentGraphService, IDeployPipelineService, IEmailService, IEmailTransport, IExportService, IFeedService, IGraphQLService, IHttpRequest, IHttpResponse, IHttpServer, II18nService, IJobService, IKV, ILock, IMetadataService, INotificationService, IPackageService, IPluginLifecycleEvents, IPluginValidator, IProvisioningService, IPubSub, IQueueService, IRealtimeService, IReportService, ISchemaDiffService, ISchemaDriver, ISearchService, ISeedLoaderService, IServiceRegistry, ISharingRuleService, ISharingService, IStartupOrchestrator, IStorageService, ITeamGraphService, ITenantRouter, ITursoPlatformService, ITypedEventEmitter, IUIService, IWorkflowService, InstallPackageInput, InstallPackageResult, IntrospectedColumn, IntrospectedIndex, IntrospectedSchema, IntrospectedTable, JobExecution, JobHandler, JobSchedule, KVEntry, KVSetOptions, LLMAdapter, ListExportJobsOptions, ListFeedOptions, LockAcquireOptions, LockHandle, Logger, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle, Middleware, MigrationApplyResult, NormalizedEmailMessage, NotificationChannel, NotificationMessage, NotificationResult, PendingActionRow, PendingActionStatus, PlanUpgradeInput, Plugin, PluginStartupResult, PresignedDownloadDescriptor, PresignedUploadDescriptor, ProposePendingActionInput, PubSubHandler, PubSubMessage, PublishOptions, QueueBackoffPolicy, QueueHandler, QueueMessage, QueueMessageRecord, QueuePublishOptions, RealtimeEventHandler, RealtimeEventPayload, RealtimeSubscriptionFilter, RealtimeSubscriptionOptions, RecordShare, ReportFormat, ReportQuery, ReportRunResult, ReportSchedule, ResolveDependenciesInput, ResolvedTenantContext, RollbackInput, RouteHandler, SaveReportInput, SavedReport, ScheduleExportInput, ScheduleReportInput, SearchHit, SearchOptions, SearchResult, SendEmailInput, SendEmailResult, SendTemplateInput, ShareAccessLevel, ShareRecipientType, ShareSource, SharingExecutionContext, SharingRuleEvaluationResult, SharingRuleRecipientType, SharingRuleRow, StartupOptions, StorageFileInfo, StorageUploadOptions, StrategyContext, SubmitApprovalInput, SubscribeInput, SubscribeOptions, TransportSendResult, TursoDatabaseInfo, TursoTokenResult, TursoTokenScope, Unsubscribe, UpdateFeedItemInput, UploadArtifactInput, UploadArtifactResult, ValidationResult, WorkflowStatus, WorkflowTransition, WorkflowTransitionResult };
+export { type AIConversation, type AIMessage, type AIMessageWithTools, type AIObjectResult, type AIRequestOptions, type AIRequestOptionsWithTools, type AIResult, type AIStreamEvent, type AIToolCall, type AIToolDefinition, type AIToolResult, type AdapterContext, type AdapterSearchOptions, type AnalyticsQuery, type AnalyticsResult, type AnalyticsStrategy, type ApprovalActionRow, type ApprovalDecisionInput, type ApprovalDecisionResult, type ApprovalProcessRow, type ApprovalRequestRow, type ApprovalStatus, type AuthResult, type AuthSession, type AuthUser, type AutomationContext, type AutomationResult, type CacheStats, type ChatWithToolsOptions, type CheckNamespaceInput, type CheckNamespaceResult, type ClusterCallContext, type CounterIncrOptions, type CreateExportJobInput, type CreateExportJobResult, type CreateFeedItemInput, type CreateTursoDatabaseOptions, type CryptoContext, type CryptoHandle, type CubeMeta, type DefineApprovalProcessInput, type DefineSharingRuleInput, type DeployExecutionResult, type DriverCapabilities, type DriverInterface, type EmailAddress, type EmailAttachment, type EmailDeliveryStatus, type ExecuteUpgradeInput, type ExportJobDownload, type ExportJobListResult, type FeedListResult, type GenerateObjectOptions, type GrantShareInput, type GraphQLRequest, type GraphQLResponse, type HealthStatus, type IAIConversationService, type IAIService, type IAdvancedServiceRegistry, type IAnalyticsService, type IAppLifecycleService, type IApprovalService, type IAuthService, type IAutomationService, type IBasicServiceRegistry, type ICacheService, type IClusterService, type ICounter, type ICryptoProvider, type IDataDriver, type IDataEngine, type IDepartmentGraphService, type IDeployPipelineService, type IEmailService, type IEmailTransport, type IExportService, type IFeedService, type IGraphQLService, type IHttpRequest, type IHttpResponse, type IHttpServer, type II18nService, type IJobService, type IKV, type IKnowledgeAdapter, type IKnowledgeService, type ILock, type IMetadataService, type INotificationService, type IPackageService, type IPluginLifecycleEvents, type IPluginValidator, type IProvisioningService, type IPubSub, type IQueueService, type IRealtimeService, type IReportService, type ISchemaDiffService, type ISchemaDriver, type ISearchService, type ISeedLoaderService, type IServiceRegistry, type ISharingRuleService, type ISharingService, type IStartupOrchestrator, type IStorageService, type ITeamGraphService, type ITenantRouter, type ITursoPlatformService, type ITypedEventEmitter, type IUIService, type IWorkflowService, type InstallPackageInput, type InstallPackageResult, type IntrospectedColumn, type IntrospectedIndex, type IntrospectedSchema, type IntrospectedTable, type JobExecution, type JobHandler, type JobSchedule, KNOWLEDGE_SERVICE, type KVEntry, type KVSetOptions, type KnowledgeReindexOptions, type KnowledgeReindexResult, type KnowledgeSearchOptions, type LLMAdapter, type ListExportJobsOptions, type ListFeedOptions, type LockAcquireOptions, type LockHandle, type Logger, type MetadataExportOptions, type MetadataImportOptions, type MetadataImportResult, type MetadataTypeInfo, type MetadataWatchCallback, type MetadataWatchHandle, type Middleware, type MigrationApplyResult, type NormalizedEmailMessage, type NotificationChannel, type NotificationMessage, type NotificationResult, type PendingActionRow, type PendingActionStatus, type PlanUpgradeInput, type Plugin, type PluginStartupResult, type PresignedDownloadDescriptor, type PresignedUploadDescriptor, type ProposePendingActionInput, type PubSubHandler, type PubSubMessage, type PublishOptions, type QueueBackoffPolicy, type QueueHandler, type QueueMessage, type QueueMessageRecord, type QueuePublishOptions, type RealtimeEventHandler, type RealtimeEventPayload, type RealtimeSubscriptionFilter, type RealtimeSubscriptionOptions, type RecordShare, type ReportFormat, type ReportQuery, type ReportRunResult, type ReportSchedule, type ResolveDependenciesInput, type ResolvedTenantContext, type RollbackInput, type RouteHandler, type SaveReportInput, type SavedReport, type ScheduleExportInput, type ScheduleReportInput, type SearchHit, type SearchOptions, type SearchResult, type SendEmailInput, type SendEmailResult, type SendTemplateInput, type ShareAccessLevel, type ShareRecipientType, type ShareSource, type SharingExecutionContext, type SharingRuleEvaluationResult, type SharingRuleRecipientType, type SharingRuleRow, type StartupOptions, type StorageFileInfo, type StorageUploadOptions, type StrategyContext, type SubmitApprovalInput, type SubscribeInput, type SubscribeOptions, type ToolExecutionContext, type TransportSendResult, type TursoDatabaseInfo, type TursoTokenResult, type TursoTokenScope, type Unsubscribe, type UpdateFeedItemInput, type UploadArtifactInput, type UploadArtifactResult, type ValidationResult, type WorkflowStatus, type WorkflowTransition, type WorkflowTransitionResult };

package/dist/contracts/index.js

@@ -1,4 +1,8 @@
 'use strict';
 
+// src/contracts/knowledge-service.ts
+var KNOWLEDGE_SERVICE = "knowledge";
+
+exports.KNOWLEDGE_SERVICE = KNOWLEDGE_SERVICE;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/contracts/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}
+{"version":3,"sources":["../../src/contracts/knowledge-service.ts"],"names":[],"mappings":";;;AAgHO,IAAM,iBAAA,GAAoB","file":"index.js","sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { ExecutionContext } from '../kernel/execution-context.zod';\nimport type {\n  KnowledgeDocument,\n  KnowledgeHit,\n} from '../ai/knowledge-document.zod';\nimport type { KnowledgeSource } from '../ai/knowledge-source.zod';\nimport type { IKnowledgeAdapter } from './knowledge-adapter';\n\n/**\n * `IKnowledgeService` — orchestrator contract consumed by REST,\n * `service-ai`, Studio, and custom plugins. Implemented by\n * `@objectstack/service-knowledge`.\n *\n * The service routes requests to one of many `IKnowledgeAdapter`\n * plugins (RAGFlow, LlamaIndex, Dify, …), wraps search results with a\n * permission-aware filter that uses the caller's `ExecutionContext`,\n * and drives event-based sync from ObjectQL.\n *\n * See `content/docs/protocol/knowledge.mdx` for the architecture\n * rationale.\n */\n\n/** Options accepted by `IKnowledgeService.search`. */\nexport interface KnowledgeSearchOptions {\n  /**\n   * Restrict the search to the given source ids. When omitted, every\n   * source the caller is allowed to see is queried.\n   */\n  sourceIds?: string[];\n  /** Max number of hits to return. Adapters may cap further. */\n  topK?: number;\n  /** Adapter-specific filter (passed opaquely). */\n  filter?: Record<string, unknown>;\n  /**\n   * Execution context of the caller. **Required** for permission-aware\n   * retrieval: hits whose `sourceRecordId` would be filtered out by\n   * RLS are dropped before being returned. Internal callers may pass\n   * an `isSystem: true` context to bypass — same convention as\n   * `IDataEngine`.\n   */\n  executionContext?: ExecutionContext;\n}\n\n/** Options accepted by `IKnowledgeService.reindexSource`. */\nexport interface KnowledgeReindexOptions {\n  /** When `true`, walk the source and count but do not call the adapter. */\n  dryRun?: boolean;\n  /** Cap on number of documents to reindex (mostly for tests / smoke runs). */\n  limit?: number;\n}\n\n/** Result of a `reindexSource` call. */\nexport interface KnowledgeReindexResult {\n  /** Number of documents pushed to the adapter (0 when dryRun). */\n  indexed: number;\n  /** Number of documents discovered (always populated). */\n  discovered: number;\n  /** When applicable, the underlying object's short name. */\n  object?: string;\n  /** When `false`, an adapter / source check prevented the run. */\n  ok: boolean;\n  /** Free-form diagnostics. */\n  message?: string;\n}\n\n/**\n * Core service contract.\n *\n * Every adapter plugin calls `registerAdapter(id, this)` during its\n * `start()` hook. Sources reference adapters by id; unknown ids cause\n * `search` / `indexDocument` to throw early with a clear error.\n */\nexport interface IKnowledgeService {\n  /** Register (or replace) an adapter under the given id. */\n  registerAdapter(id: string, adapter: IKnowledgeAdapter): void;\n  /** Resolve an adapter by id. Throws when unknown. */\n  getAdapter(id: string): IKnowledgeAdapter;\n  /** Enumerate registered adapter ids. */\n  listAdapters(): string[];\n\n  /** Register a logical knowledge source. */\n  registerSource(source: KnowledgeSource): void;\n  /** Remove a registered source. Does not delete underlying data. */\n  unregisterSource(sourceId: string): void;\n  /** Snapshot of registered sources (read-only). */\n  listSources(): KnowledgeSource[];\n  /** Look up a single source. Returns `undefined` when not registered. */\n  getSource(sourceId: string): KnowledgeSource | undefined;\n\n  /** Index (insert or replace) a document into the source's adapter. */\n  indexDocument(sourceId: string, doc: KnowledgeDocument): Promise<void>;\n  /** Remove a document from the source's adapter. */\n  deleteDocument(sourceId: string, documentId: string): Promise<void>;\n\n  /**\n   * Bulk reindex a source from its declared origin. Object sources\n   * walk the underlying object via `IDataEngine`; file / http sources\n   * delegate to the adapter's own ingestion.\n   */\n  reindexSource(sourceId: string, opts?: KnowledgeReindexOptions): Promise<KnowledgeReindexResult>;\n\n  /**\n   * Run a search across one or more sources. Results are\n   * permission-filtered before being returned (see\n   * `KnowledgeSearchOptions.executionContext`).\n   */\n  search(query: string, opts?: KnowledgeSearchOptions): Promise<KnowledgeHit[]>;\n}\n\n/** Canonical service-registry id used by `IKnowledgeService` consumers. */\nexport const KNOWLEDGE_SERVICE = 'knowledge' as const;\n"]}

package/dist/contracts/index.mjs

@@ -1,3 +1,6 @@
+// src/contracts/knowledge-service.ts
+var KNOWLEDGE_SERVICE = "knowledge";
 
+export { KNOWLEDGE_SERVICE };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/contracts/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}
+{"version":3,"sources":["../../src/contracts/knowledge-service.ts"],"names":[],"mappings":";AAgHO,IAAM,iBAAA,GAAoB","file":"index.mjs","sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { ExecutionContext } from '../kernel/execution-context.zod';\nimport type {\n  KnowledgeDocument,\n  KnowledgeHit,\n} from '../ai/knowledge-document.zod';\nimport type { KnowledgeSource } from '../ai/knowledge-source.zod';\nimport type { IKnowledgeAdapter } from './knowledge-adapter';\n\n/**\n * `IKnowledgeService` — orchestrator contract consumed by REST,\n * `service-ai`, Studio, and custom plugins. Implemented by\n * `@objectstack/service-knowledge`.\n *\n * The service routes requests to one of many `IKnowledgeAdapter`\n * plugins (RAGFlow, LlamaIndex, Dify, …), wraps search results with a\n * permission-aware filter that uses the caller's `ExecutionContext`,\n * and drives event-based sync from ObjectQL.\n *\n * See `content/docs/protocol/knowledge.mdx` for the architecture\n * rationale.\n */\n\n/** Options accepted by `IKnowledgeService.search`. */\nexport interface KnowledgeSearchOptions {\n  /**\n   * Restrict the search to the given source ids. When omitted, every\n   * source the caller is allowed to see is queried.\n   */\n  sourceIds?: string[];\n  /** Max number of hits to return. Adapters may cap further. */\n  topK?: number;\n  /** Adapter-specific filter (passed opaquely). */\n  filter?: Record<string, unknown>;\n  /**\n   * Execution context of the caller. **Required** for permission-aware\n   * retrieval: hits whose `sourceRecordId` would be filtered out by\n   * RLS are dropped before being returned. Internal callers may pass\n   * an `isSystem: true` context to bypass — same convention as\n   * `IDataEngine`.\n   */\n  executionContext?: ExecutionContext;\n}\n\n/** Options accepted by `IKnowledgeService.reindexSource`. */\nexport interface KnowledgeReindexOptions {\n  /** When `true`, walk the source and count but do not call the adapter. */\n  dryRun?: boolean;\n  /** Cap on number of documents to reindex (mostly for tests / smoke runs). */\n  limit?: number;\n}\n\n/** Result of a `reindexSource` call. */\nexport interface KnowledgeReindexResult {\n  /** Number of documents pushed to the adapter (0 when dryRun). */\n  indexed: number;\n  /** Number of documents discovered (always populated). */\n  discovered: number;\n  /** When applicable, the underlying object's short name. */\n  object?: string;\n  /** When `false`, an adapter / source check prevented the run. */\n  ok: boolean;\n  /** Free-form diagnostics. */\n  message?: string;\n}\n\n/**\n * Core service contract.\n *\n * Every adapter plugin calls `registerAdapter(id, this)` during its\n * `start()` hook. Sources reference adapters by id; unknown ids cause\n * `search` / `indexDocument` to throw early with a clear error.\n */\nexport interface IKnowledgeService {\n  /** Register (or replace) an adapter under the given id. */\n  registerAdapter(id: string, adapter: IKnowledgeAdapter): void;\n  /** Resolve an adapter by id. Throws when unknown. */\n  getAdapter(id: string): IKnowledgeAdapter;\n  /** Enumerate registered adapter ids. */\n  listAdapters(): string[];\n\n  /** Register a logical knowledge source. */\n  registerSource(source: KnowledgeSource): void;\n  /** Remove a registered source. Does not delete underlying data. */\n  unregisterSource(sourceId: string): void;\n  /** Snapshot of registered sources (read-only). */\n  listSources(): KnowledgeSource[];\n  /** Look up a single source. Returns `undefined` when not registered. */\n  getSource(sourceId: string): KnowledgeSource | undefined;\n\n  /** Index (insert or replace) a document into the source's adapter. */\n  indexDocument(sourceId: string, doc: KnowledgeDocument): Promise<void>;\n  /** Remove a document from the source's adapter. */\n  deleteDocument(sourceId: string, documentId: string): Promise<void>;\n\n  /**\n   * Bulk reindex a source from its declared origin. Object sources\n   * walk the underlying object via `IDataEngine`; file / http sources\n   * delegate to the adapter's own ingestion.\n   */\n  reindexSource(sourceId: string, opts?: KnowledgeReindexOptions): Promise<KnowledgeReindexResult>;\n\n  /**\n   * Run a search across one or more sources. Results are\n   * permission-filtered before being returned (see\n   * `KnowledgeSearchOptions.executionContext`).\n   */\n  search(query: string, opts?: KnowledgeSearchOptions): Promise<KnowledgeHit[]>;\n}\n\n/** Canonical service-registry id used by `IKnowledgeService` consumers. */\nexport const KNOWLEDGE_SERVICE = 'knowledge' as const;\n"]}

package/dist/{manifest.zod-ZIjKKFkz.d.mts → execution-context.zod-7FfY8UW2.d.mts}

@@ -2578,4 +2578,17 @@ declare const ManifestSchema: z.ZodObject<{
 type ObjectStackManifest = z.infer<typeof ManifestSchema>;
 type ObjectStackManifestInput = z.input<typeof ManifestSchema>;
 
-export { MetadataValidationResultSchema as $, type ArtifactChecksum as A, MetadataChangeTypeSchema as B, type CustomizationOrigin as C, DEFAULT_METADATA_TYPE_REGISTRY as D, type MetadataDependency as E, type FieldChange as F, MetadataDependencySchema as G, type MetadataDiffItem as H, MetadataDiffItemSchema as I, type MetadataEvent as J, MetadataEventSchema as K, type MetadataOverlay as L, ManifestSchema as M, MetadataOverlaySchema as N, type MetadataPluginConfig as O, MetadataPluginConfigSchema as P, type MetadataPluginManifest as Q, MetadataPluginManifestSchema as R, type MetadataQuery as S, type MetadataQueryResult as T, MetadataQueryResultSchema as U, MetadataQuerySchema as V, type MetadataType as W, type MetadataTypeRegistryEntry as X, MetadataTypeRegistryEntrySchema as Y, MetadataTypeSchema as Z, type MetadataValidationResult as _, ArtifactChecksumSchema as a, type ObjectStackManifest as a0, type ObjectStackManifestInput as a1, type PackageArtifact as a2, type PackageArtifactInput as a3, PackageArtifactSchema as a4, type RequiredAction as a5, RequiredActionSchema as a6, type ResolvedDependency as a7, ResolvedDependencySchema as a8, type RollbackPackageRequest as a9, RollbackPackageRequestSchema as aa, type RollbackPackageResponse as ab, RollbackPackageResponseSchema as ac, type UpgradeImpactLevel as ad, UpgradeImpactLevelSchema as ae, type UpgradePackageRequest as af, UpgradePackageRequestSchema as ag, type UpgradePackageResponse as ah, UpgradePackageResponseSchema as ai, type UpgradePhase as aj, UpgradePhaseSchema as ak, type UpgradePlan as al, UpgradePlanSchema as am, type UpgradeSnapshot as an, UpgradeSnapshotSchema as ao, type ArtifactFileEntry as b, ArtifactFileEntrySchema as c, type ArtifactSignature as d, ArtifactSignatureSchema as e, CustomizationOriginSchema as f, type CustomizationPolicy as g, CustomizationPolicySchema as h, type DependencyResolutionResult as i, DependencyResolutionResultSchema as j, type DependencyStatus as k, DependencyStatusEnum as l, FieldChangeSchema as m, type MergeConflict as n, MergeConflictSchema as o, type MergeResult as p, MergeResultSchema as q, type MergeStrategyConfig as r, MergeStrategyConfigSchema as s, type MetadataBulkRegisterRequest as t, MetadataBulkRegisterRequestSchema as u, type MetadataBulkResult as v, MetadataBulkResultSchema as w, type MetadataCategory as x, MetadataCategoryEnum as y, type MetadataChangeType as z };
+declare const ExecutionContextSchema: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    permissions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    org_user_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    isSystem: z.ZodDefault<z.ZodBoolean>;
+    accessToken: z.ZodOptional<z.ZodString>;
+    transaction: z.ZodOptional<z.ZodUnknown>;
+    traceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ExecutionContext = z.infer<typeof ExecutionContextSchema>;
+
+export { MetadataTypeSchema as $, type ArtifactChecksum as A, type MetadataChangeType as B, type CustomizationOrigin as C, DEFAULT_METADATA_TYPE_REGISTRY as D, type ExecutionContext as E, type FieldChange as F, MetadataChangeTypeSchema as G, type MetadataDependency as H, MetadataDependencySchema as I, type MetadataDiffItem as J, MetadataDiffItemSchema as K, type MetadataEvent as L, ManifestSchema as M, MetadataEventSchema as N, type MetadataOverlay as O, MetadataOverlaySchema as P, type MetadataPluginConfig as Q, MetadataPluginConfigSchema as R, type MetadataPluginManifest as S, MetadataPluginManifestSchema as T, type MetadataQuery as U, type MetadataQueryResult as V, MetadataQueryResultSchema as W, MetadataQuerySchema as X, type MetadataType as Y, type MetadataTypeRegistryEntry as Z, MetadataTypeRegistryEntrySchema as _, ArtifactChecksumSchema as a, type MetadataValidationResult as a0, MetadataValidationResultSchema as a1, type ObjectStackManifest as a2, type ObjectStackManifestInput as a3, type PackageArtifact as a4, type PackageArtifactInput as a5, PackageArtifactSchema as a6, type RequiredAction as a7, RequiredActionSchema as a8, type ResolvedDependency as a9, ResolvedDependencySchema as aa, type RollbackPackageRequest as ab, RollbackPackageRequestSchema as ac, type RollbackPackageResponse as ad, RollbackPackageResponseSchema as ae, type UpgradeImpactLevel as af, UpgradeImpactLevelSchema as ag, type UpgradePackageRequest as ah, UpgradePackageRequestSchema as ai, type UpgradePackageResponse as aj, UpgradePackageResponseSchema as ak, type UpgradePhase as al, UpgradePhaseSchema as am, type UpgradePlan as an, UpgradePlanSchema as ao, type UpgradeSnapshot as ap, UpgradeSnapshotSchema as aq, type ArtifactFileEntry as b, ArtifactFileEntrySchema as c, type ArtifactSignature as d, ArtifactSignatureSchema as e, CustomizationOriginSchema as f, type CustomizationPolicy as g, CustomizationPolicySchema as h, type DependencyResolutionResult as i, DependencyResolutionResultSchema as j, type DependencyStatus as k, DependencyStatusEnum as l, ExecutionContextSchema as m, FieldChangeSchema as n, type MergeConflict as o, MergeConflictSchema as p, type MergeResult as q, MergeResultSchema as r, type MergeStrategyConfig as s, MergeStrategyConfigSchema as t, type MetadataBulkRegisterRequest as u, MetadataBulkRegisterRequestSchema as v, type MetadataBulkResult as w, MetadataBulkResultSchema as x, type MetadataCategory as y, MetadataCategoryEnum as z };

package/dist/{manifest.zod-ZIjKKFkz.d.ts → execution-context.zod-7FfY8UW2.d.ts}

@@ -2578,4 +2578,17 @@ declare const ManifestSchema: z.ZodObject<{
 type ObjectStackManifest = z.infer<typeof ManifestSchema>;
 type ObjectStackManifestInput = z.input<typeof ManifestSchema>;
 
-export { MetadataValidationResultSchema as $, type ArtifactChecksum as A, MetadataChangeTypeSchema as B, type CustomizationOrigin as C, DEFAULT_METADATA_TYPE_REGISTRY as D, type MetadataDependency as E, type FieldChange as F, MetadataDependencySchema as G, type MetadataDiffItem as H, MetadataDiffItemSchema as I, type MetadataEvent as J, MetadataEventSchema as K, type MetadataOverlay as L, ManifestSchema as M, MetadataOverlaySchema as N, type MetadataPluginConfig as O, MetadataPluginConfigSchema as P, type MetadataPluginManifest as Q, MetadataPluginManifestSchema as R, type MetadataQuery as S, type MetadataQueryResult as T, MetadataQueryResultSchema as U, MetadataQuerySchema as V, type MetadataType as W, type MetadataTypeRegistryEntry as X, MetadataTypeRegistryEntrySchema as Y, MetadataTypeSchema as Z, type MetadataValidationResult as _, ArtifactChecksumSchema as a, type ObjectStackManifest as a0, type ObjectStackManifestInput as a1, type PackageArtifact as a2, type PackageArtifactInput as a3, PackageArtifactSchema as a4, type RequiredAction as a5, RequiredActionSchema as a6, type ResolvedDependency as a7, ResolvedDependencySchema as a8, type RollbackPackageRequest as a9, RollbackPackageRequestSchema as aa, type RollbackPackageResponse as ab, RollbackPackageResponseSchema as ac, type UpgradeImpactLevel as ad, UpgradeImpactLevelSchema as ae, type UpgradePackageRequest as af, UpgradePackageRequestSchema as ag, type UpgradePackageResponse as ah, UpgradePackageResponseSchema as ai, type UpgradePhase as aj, UpgradePhaseSchema as ak, type UpgradePlan as al, UpgradePlanSchema as am, type UpgradeSnapshot as an, UpgradeSnapshotSchema as ao, type ArtifactFileEntry as b, ArtifactFileEntrySchema as c, type ArtifactSignature as d, ArtifactSignatureSchema as e, CustomizationOriginSchema as f, type CustomizationPolicy as g, CustomizationPolicySchema as h, type DependencyResolutionResult as i, DependencyResolutionResultSchema as j, type DependencyStatus as k, DependencyStatusEnum as l, FieldChangeSchema as m, type MergeConflict as n, MergeConflictSchema as o, type MergeResult as p, MergeResultSchema as q, type MergeStrategyConfig as r, MergeStrategyConfigSchema as s, type MetadataBulkRegisterRequest as t, MetadataBulkRegisterRequestSchema as u, type MetadataBulkResult as v, MetadataBulkResultSchema as w, type MetadataCategory as x, MetadataCategoryEnum as y, type MetadataChangeType as z };
+declare const ExecutionContextSchema: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    permissions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    org_user_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    isSystem: z.ZodDefault<z.ZodBoolean>;
+    accessToken: z.ZodOptional<z.ZodString>;
+    transaction: z.ZodOptional<z.ZodUnknown>;
+    traceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ExecutionContext = z.infer<typeof ExecutionContextSchema>;
+
+export { MetadataTypeSchema as $, type ArtifactChecksum as A, type MetadataChangeType as B, type CustomizationOrigin as C, DEFAULT_METADATA_TYPE_REGISTRY as D, type ExecutionContext as E, type FieldChange as F, MetadataChangeTypeSchema as G, type MetadataDependency as H, MetadataDependencySchema as I, type MetadataDiffItem as J, MetadataDiffItemSchema as K, type MetadataEvent as L, ManifestSchema as M, MetadataEventSchema as N, type MetadataOverlay as O, MetadataOverlaySchema as P, type MetadataPluginConfig as Q, MetadataPluginConfigSchema as R, type MetadataPluginManifest as S, MetadataPluginManifestSchema as T, type MetadataQuery as U, type MetadataQueryResult as V, MetadataQueryResultSchema as W, MetadataQuerySchema as X, type MetadataType as Y, type MetadataTypeRegistryEntry as Z, MetadataTypeRegistryEntrySchema as _, ArtifactChecksumSchema as a, type MetadataValidationResult as a0, MetadataValidationResultSchema as a1, type ObjectStackManifest as a2, type ObjectStackManifestInput as a3, type PackageArtifact as a4, type PackageArtifactInput as a5, PackageArtifactSchema as a6, type RequiredAction as a7, RequiredActionSchema as a8, type ResolvedDependency as a9, ResolvedDependencySchema as aa, type RollbackPackageRequest as ab, RollbackPackageRequestSchema as ac, type RollbackPackageResponse as ad, RollbackPackageResponseSchema as ae, type UpgradeImpactLevel as af, UpgradeImpactLevelSchema as ag, type UpgradePackageRequest as ah, UpgradePackageRequestSchema as ai, type UpgradePackageResponse as aj, UpgradePackageResponseSchema as ak, type UpgradePhase as al, UpgradePhaseSchema as am, type UpgradePlan as an, UpgradePlanSchema as ao, type UpgradeSnapshot as ap, UpgradeSnapshotSchema as aq, type ArtifactFileEntry as b, ArtifactFileEntrySchema as c, type ArtifactSignature as d, ArtifactSignatureSchema as e, CustomizationOriginSchema as f, type CustomizationPolicy as g, CustomizationPolicySchema as h, type DependencyResolutionResult as i, DependencyResolutionResultSchema as j, type DependencyStatus as k, DependencyStatusEnum as l, ExecutionContextSchema as m, FieldChangeSchema as n, type MergeConflict as o, MergeConflictSchema as p, type MergeResult as q, MergeResultSchema as r, type MergeStrategyConfig as s, MergeStrategyConfigSchema as t, type MetadataBulkRegisterRequest as u, MetadataBulkRegisterRequestSchema as v, type MetadataBulkResult as w, MetadataBulkResultSchema as x, type MetadataCategory as y, MetadataCategoryEnum as z };