@objectstack/spec 6.8.1 → 6.9.0

package/dist/contracts/index.d.mts

@@ -1,9 +1,9 @@
 import { Y as DriverCapabilities$1, a2 as DriverOptions, aa as EngineQueryOptions, v as DataEngineInsertOptions, ac as EngineUpdateOptions, a8 as EngineDeleteOptions, a6 as EngineCountOptions, a4 as EngineAggregateOptions, E as DataEngineRequest, C as Cube, ah as FeedItem, ay as Reaction, aA as RecordSubscription, aG as SQLDialect, aR as SeedLoaderRequest, aU as SeedLoaderResult, as as ObjectDependencyGraph, O as Dataset, aP as SeedLoaderConfigInput } from '../subscription.zod-MSheiEQT.mjs';
 import { Q as QueryAST } from '../query.zod-C-iygIgx.mjs';
 import { z } from 'zod';
-import { u as ObjectSchema } from '../object.zod-C1mmiCDL.mjs';
+import { u as ObjectSchema } from '../object.zod-CATh64Wi.mjs';
 import { k as FieldSchema } from '../field.zod-BGr7R7KU.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-D4xMP7B4.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-INizjS3v.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-LPphSOut.mjs';
 import { i as ExecutionLog } from '../execution.zod-DGGOFfcb.mjs';
@@ -3863,6 +3863,134 @@ interface IDepartmentGraphService {
     managerOf(userId: string, organizationId?: string): Promise<string | null>;
 }
 
+/**
+ * @objectstack/spec/contracts/share-link-service
+ *
+ * Capability-token sharing — "anyone with the link" publication of a
+ * single record. Complementary to `ISharingService`, which models
+ * principal-based grants (share with specific users / teams / roles).
+ *
+ * Design notes:
+ *
+ *   1. **Opaque tokens.** A share link is a single random `token`
+ *      (>=22 chars from a URL-safe alphabet). Anyone holding the
+ *      token can fetch the record subject to `audience` and
+ *      `expires_at`. Tokens are *not* derived from the record id;
+ *      enumerating record ids reveals nothing.
+ *
+ *   2. **Per-object opt-in.** `createLink` refuses to mint a token
+ *      for an object whose schema does not set `publicSharing.enabled`.
+ *      The audience / permission requested must also lie within the
+ *      object's `allowedAudiences` / `allowedPermissions` whitelist.
+ *
+ *   3. **Field-level redaction.** Each resolved link returns a
+ *      `redactFields` set (object-default ∪ per-link). The REST gateway
+ *      strips these before serialising to the response — the engine
+ *      itself sees the raw row so existing hooks fire normally.
+ *
+ *   4. **No principal expansion.** Holders of a share token are NOT
+ *      treated as principals in `sys_record_share`; the token authorises
+ *      access only to its single `(object, recordId)` tuple at the
+ *      declared `permission` level. This keeps audit trails clean and
+ *      prevents lateral movement.
+ */
+/** Levels selectable when issuing a link. */
+type ShareLinkPermission = 'view' | 'comment' | 'edit';
+/** Audience gating. */
+type ShareLinkAudience = 'public' | 'link_only' | 'signed_in' | 'email';
+/** Persisted shape — mirrors `sys_share_link` columns 1:1. */
+interface ShareLink {
+    id: string;
+    /** Opaque URL-safe token. Always present; the only secret. */
+    token: string;
+    object_name: string;
+    record_id: string;
+    permission: ShareLinkPermission;
+    audience: ShareLinkAudience;
+    /** ISO timestamp; null means no expiry. */
+    expires_at?: string | null;
+    /** When `audience='email'`, the allow-listed addresses (lowercased). */
+    email_allowlist?: string[] | null;
+    /** Optional argon2/bcrypt hash; UI prompts for a password when set. */
+    password_hash?: string | null;
+    /** Per-link extra redactions, layered on top of the object-default set. */
+    redact_fields?: string[] | null;
+    /** Free-text shown in the share dialog (e.g. "Q3 contract for ACME"). */
+    label?: string | null;
+    /** When set, the link is revoked and `resolveToken` returns null. */
+    revoked_at?: string | null;
+    created_by?: string | null;
+    created_at?: string;
+    last_used_at?: string | null;
+    use_count?: number;
+}
+/** Input for {@link IShareLinkService.createLink}. */
+interface CreateShareLinkInput {
+    object: string;
+    recordId: string;
+    permission?: ShareLinkPermission;
+    audience?: ShareLinkAudience;
+    /** ISO timestamp or relative duration string ("7d", "24h") — service normalises. */
+    expiresAt?: string | null;
+    emailAllowlist?: string[];
+    /** Plain-text password; service hashes before persisting. */
+    password?: string;
+    /** Per-link redactions in addition to the object default. */
+    redactFields?: string[];
+    label?: string;
+}
+/** Filter for {@link IShareLinkService.listLinks}. */
+interface ListShareLinksFilter {
+    object?: string;
+    recordId?: string;
+    createdBy?: string;
+    includeRevoked?: boolean;
+}
+/** Outcome of resolving a token via the public endpoint. */
+interface ResolveShareLinkResult {
+    link: ShareLink;
+    /** Effective fields removed from the response (object default ∪ per-link). */
+    redactFields: string[];
+}
+/** Minimal context interface — kept compatible with `SharingExecutionContext`. */
+interface ShareLinkExecutionContext {
+    userId?: string;
+    tenantId?: string;
+    isSystem?: boolean;
+}
+/**
+ * Default implementation lives in `@objectstack/plugin-sharing`.
+ *
+ * Implementations MUST treat `context.isSystem === true` as a bypass
+ * (skip the per-object opt-in check) so platform bootstrappers can seed
+ * demo links.
+ */
+interface IShareLinkService {
+    /** Mint a new link. Throws when the object is not opt-in or limits are exceeded. */
+    createLink(input: CreateShareLinkInput, context: ShareLinkExecutionContext): Promise<ShareLink>;
+    /** Mark a link as revoked. No-op when already revoked or not found. */
+    revokeLink(idOrToken: string, context: ShareLinkExecutionContext): Promise<void>;
+    /** List links for a record, an object, or a creator. */
+    listLinks(filter: ListShareLinksFilter, context: ShareLinkExecutionContext): Promise<ShareLink[]>;
+    /**
+     * Resolve a token at request-handling time. Returns null when the
+     * token does not exist, is revoked, expired, or fails the audience
+     * check. Increments `use_count` / `last_used_at` as a side effect.
+     *
+     * @param token  raw token from the URL / cookie
+     * @param probe  contextual gates the caller has already evaluated
+     *               (e.g. signed-in user, recipient email, supplied
+     *               password)
+     */
+    resolveToken(token: string, probe?: {
+        signedInUserId?: string;
+        recipientEmail?: string;
+        providedPassword?: string;
+    }): Promise<ResolveShareLinkResult | null>;
+}
+/** Service-registry key — keep in sync with the SharingPlugin registration. */
+declare const SHARE_LINK_SERVICE: "shareLinks";
+
 /**
  * @objectstack/spec/contracts/report-service
  *
@@ -5376,4 +5504,4 @@ interface IClusterService {
     close(): Promise<void>;
 }
 
-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, EMBEDDER_SERVICE, 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 IEmbedder, 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 };
+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 CreateShareLinkInput, type CreateTursoDatabaseOptions, type CryptoContext, type CryptoHandle, type CubeMeta, type DefineApprovalProcessInput, type DefineSharingRuleInput, type DeployExecutionResult, type DriverCapabilities, type DriverInterface, EMBEDDER_SERVICE, 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 IEmbedder, 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 IShareLinkService, 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 ListShareLinksFilter, 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 ResolveShareLinkResult, type ResolvedTenantContext, type RollbackInput, type RouteHandler, SHARE_LINK_SERVICE, type SaveReportInput, type SavedReport, type ScheduleExportInput, type ScheduleReportInput, type SearchHit, type SearchOptions, type SearchResult, type SendEmailInput, type SendEmailResult, type SendTemplateInput, type ShareAccessLevel, type ShareLink, type ShareLinkAudience, type ShareLinkExecutionContext, type ShareLinkPermission, 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

@@ -1,9 +1,9 @@
 import { Y as DriverCapabilities$1, a2 as DriverOptions, aa as EngineQueryOptions, v as DataEngineInsertOptions, ac as EngineUpdateOptions, a8 as EngineDeleteOptions, a6 as EngineCountOptions, a4 as EngineAggregateOptions, E as DataEngineRequest, C as Cube, ah as FeedItem, ay as Reaction, aA as RecordSubscription, aG as SQLDialect, aR as SeedLoaderRequest, aU as SeedLoaderResult, as as ObjectDependencyGraph, O as Dataset, aP as SeedLoaderConfigInput } from '../subscription.zod-CBBzN0Tf.js';
 import { Q as QueryAST } from '../query.zod-CGnJOIQH.js';
 import { z } from 'zod';
-import { u as ObjectSchema } from '../object.zod-D4gYbFv4.js';
+import { u as ObjectSchema } from '../object.zod-B2nzURDy.js';
 import { k as FieldSchema } from '../field.zod-BGr7R7KU.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-D4xMP7B4.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-INizjS3v.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-LPphSOut.js';
 import { i as ExecutionLog } from '../execution.zod-DGGOFfcb.js';
@@ -3863,6 +3863,134 @@ interface IDepartmentGraphService {
     managerOf(userId: string, organizationId?: string): Promise<string | null>;
 }
 
+/**
+ * @objectstack/spec/contracts/share-link-service
+ *
+ * Capability-token sharing — "anyone with the link" publication of a
+ * single record. Complementary to `ISharingService`, which models
+ * principal-based grants (share with specific users / teams / roles).
+ *
+ * Design notes:
+ *
+ *   1. **Opaque tokens.** A share link is a single random `token`
+ *      (>=22 chars from a URL-safe alphabet). Anyone holding the
+ *      token can fetch the record subject to `audience` and
+ *      `expires_at`. Tokens are *not* derived from the record id;
+ *      enumerating record ids reveals nothing.
+ *
+ *   2. **Per-object opt-in.** `createLink` refuses to mint a token
+ *      for an object whose schema does not set `publicSharing.enabled`.
+ *      The audience / permission requested must also lie within the
+ *      object's `allowedAudiences` / `allowedPermissions` whitelist.
+ *
+ *   3. **Field-level redaction.** Each resolved link returns a
+ *      `redactFields` set (object-default ∪ per-link). The REST gateway
+ *      strips these before serialising to the response — the engine
+ *      itself sees the raw row so existing hooks fire normally.
+ *
+ *   4. **No principal expansion.** Holders of a share token are NOT
+ *      treated as principals in `sys_record_share`; the token authorises
+ *      access only to its single `(object, recordId)` tuple at the
+ *      declared `permission` level. This keeps audit trails clean and
+ *      prevents lateral movement.
+ */
+/** Levels selectable when issuing a link. */
+type ShareLinkPermission = 'view' | 'comment' | 'edit';
+/** Audience gating. */
+type ShareLinkAudience = 'public' | 'link_only' | 'signed_in' | 'email';
+/** Persisted shape — mirrors `sys_share_link` columns 1:1. */
+interface ShareLink {
+    id: string;
+    /** Opaque URL-safe token. Always present; the only secret. */
+    token: string;
+    object_name: string;
+    record_id: string;
+    permission: ShareLinkPermission;
+    audience: ShareLinkAudience;
+    /** ISO timestamp; null means no expiry. */
+    expires_at?: string | null;
+    /** When `audience='email'`, the allow-listed addresses (lowercased). */
+    email_allowlist?: string[] | null;
+    /** Optional argon2/bcrypt hash; UI prompts for a password when set. */
+    password_hash?: string | null;
+    /** Per-link extra redactions, layered on top of the object-default set. */
+    redact_fields?: string[] | null;
+    /** Free-text shown in the share dialog (e.g. "Q3 contract for ACME"). */
+    label?: string | null;
+    /** When set, the link is revoked and `resolveToken` returns null. */
+    revoked_at?: string | null;
+    created_by?: string | null;
+    created_at?: string;
+    last_used_at?: string | null;
+    use_count?: number;
+}
+/** Input for {@link IShareLinkService.createLink}. */
+interface CreateShareLinkInput {
+    object: string;
+    recordId: string;
+    permission?: ShareLinkPermission;
+    audience?: ShareLinkAudience;
+    /** ISO timestamp or relative duration string ("7d", "24h") — service normalises. */
+    expiresAt?: string | null;
+    emailAllowlist?: string[];
+    /** Plain-text password; service hashes before persisting. */
+    password?: string;
+    /** Per-link redactions in addition to the object default. */
+    redactFields?: string[];
+    label?: string;
+}
+/** Filter for {@link IShareLinkService.listLinks}. */
+interface ListShareLinksFilter {
+    object?: string;
+    recordId?: string;
+    createdBy?: string;
+    includeRevoked?: boolean;
+}
+/** Outcome of resolving a token via the public endpoint. */
+interface ResolveShareLinkResult {
+    link: ShareLink;
+    /** Effective fields removed from the response (object default ∪ per-link). */
+    redactFields: string[];
+}
+/** Minimal context interface — kept compatible with `SharingExecutionContext`. */
+interface ShareLinkExecutionContext {
+    userId?: string;
+    tenantId?: string;
+    isSystem?: boolean;
+}
+/**
+ * Default implementation lives in `@objectstack/plugin-sharing`.
+ *
+ * Implementations MUST treat `context.isSystem === true` as a bypass
+ * (skip the per-object opt-in check) so platform bootstrappers can seed
+ * demo links.
+ */
+interface IShareLinkService {
+    /** Mint a new link. Throws when the object is not opt-in or limits are exceeded. */
+    createLink(input: CreateShareLinkInput, context: ShareLinkExecutionContext): Promise<ShareLink>;
+    /** Mark a link as revoked. No-op when already revoked or not found. */
+    revokeLink(idOrToken: string, context: ShareLinkExecutionContext): Promise<void>;
+    /** List links for a record, an object, or a creator. */
+    listLinks(filter: ListShareLinksFilter, context: ShareLinkExecutionContext): Promise<ShareLink[]>;
+    /**
+     * Resolve a token at request-handling time. Returns null when the
+     * token does not exist, is revoked, expired, or fails the audience
+     * check. Increments `use_count` / `last_used_at` as a side effect.
+     *
+     * @param token  raw token from the URL / cookie
+     * @param probe  contextual gates the caller has already evaluated
+     *               (e.g. signed-in user, recipient email, supplied
+     *               password)
+     */
+    resolveToken(token: string, probe?: {
+        signedInUserId?: string;
+        recipientEmail?: string;
+        providedPassword?: string;
+    }): Promise<ResolveShareLinkResult | null>;
+}
+/** Service-registry key — keep in sync with the SharingPlugin registration. */
+declare const SHARE_LINK_SERVICE: "shareLinks";
+
 /**
  * @objectstack/spec/contracts/report-service
  *
@@ -5376,4 +5504,4 @@ interface IClusterService {
     close(): Promise<void>;
 }
 
-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, EMBEDDER_SERVICE, 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 IEmbedder, 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 };
+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 CreateShareLinkInput, type CreateTursoDatabaseOptions, type CryptoContext, type CryptoHandle, type CubeMeta, type DefineApprovalProcessInput, type DefineSharingRuleInput, type DeployExecutionResult, type DriverCapabilities, type DriverInterface, EMBEDDER_SERVICE, 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 IEmbedder, 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 IShareLinkService, 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 ListShareLinksFilter, 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 ResolveShareLinkResult, type ResolvedTenantContext, type RollbackInput, type RouteHandler, SHARE_LINK_SERVICE, type SaveReportInput, type SavedReport, type ScheduleExportInput, type ScheduleReportInput, type SearchHit, type SearchOptions, type SearchResult, type SendEmailInput, type SendEmailResult, type SendTemplateInput, type ShareAccessLevel, type ShareLink, type ShareLinkAudience, type ShareLinkExecutionContext, type ShareLinkPermission, 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,5 +1,8 @@
 'use strict';
 
+// src/contracts/share-link-service.ts
+var SHARE_LINK_SERVICE = "shareLinks";
+
 // src/contracts/knowledge-service.ts
 var KNOWLEDGE_SERVICE = "knowledge";
 
@@ -8,5 +11,6 @@ var EMBEDDER_SERVICE = "embedder";
 
 exports.EMBEDDER_SERVICE = EMBEDDER_SERVICE;
 exports.KNOWLEDGE_SERVICE = KNOWLEDGE_SERVICE;
+exports.SHARE_LINK_SERVICE = SHARE_LINK_SERVICE;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/contracts/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/contracts/knowledge-service.ts","../../src/contracts/embedder.ts"],"names":[],"mappings":";;;AAgHO,IAAM,iBAAA,GAAoB;;;AC1D1B,IAAM,gBAAA,GAAmB","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","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `IEmbedder` — protocol-level contract for text → vector providers.\n *\n * Implemented by embedder plugins (`@objectstack/embedder-openai`,\n * `@objectstack/embedder-ollama`, `@objectstack/embedder-transformers-js`,\n * …) and consumed by every knowledge adapter that needs to compute\n * vectors (e.g. `@objectstack/knowledge-turso`,\n * `@objectstack/knowledge-sqlite-vec`).\n *\n * The surface is deliberately minimal so the same protocol covers\n * cloud APIs (OpenAI, 阿里通义, 智谱, 硅基流动, Doubao, …), local\n * Ollama daemons, in-process WASM/ONNX runtimes, and any OpenAI-shape\n * compatible endpoint. Implementations are responsible for batching,\n * retry, and rate-limit handling against their upstream.\n *\n * Conventions:\n *  - Output order MUST match input order exactly.\n *  - Vectors SHOULD be L2-normalised so downstream cosine == dot.\n *  - `dimensions` MUST be stable for the lifetime of the instance —\n *    knowledge adapters size their vector columns from this value.\n *\n * See `content/docs/protocol/knowledge.mdx`.\n */\nexport interface IEmbedder {\n  /** Stable id for logs and diagnostics (e.g. `'openai'`, `'ollama'`). */\n  readonly id: string;\n  /**\n   * Output vector dimensionality. Knowledge adapters use this to size\n   * their fixed-width vector columns / index parameters.\n   */\n  readonly dimensions: number;\n  /**\n   * Embed a batch of strings. Output order matches input order.\n   * Implementations SHOULD handle empty input by returning `[]`.\n   */\n  embed(texts: string[]): Promise<number[][]>;\n}\n\n/**\n * DI service token for the kernel-registered `IEmbedder` instance.\n *\n * Plugins that need an embedder (e.g. `@objectstack/knowledge-turso`,\n * `@objectstack/knowledge-sqlite-vec`) SHOULD prefer resolving this\n * service over taking the embedder as a constructor option, so\n * operators can configure the embedder once (in `Settings → AI &\n * Embedder`) and have every knowledge adapter pick it up.\n *\n * Registered by `@objectstack/service-ai` when the operator selects a\n * non-`none` embedder provider in settings. If absent, knowledge\n * adapters fall back to their constructor-supplied embedder (or refuse\n * to start).\n */\nexport const EMBEDDER_SERVICE = 'embedder' as const;\n"]}
+{"version":3,"sources":["../../src/contracts/share-link-service.ts","../../src/contracts/knowledge-service.ts","../../src/contracts/embedder.ts"],"names":[],"mappings":";;;AA+IO,IAAM,kBAAA,GAAqB;;;AC/B3B,IAAM,iBAAA,GAAoB;;;AC1D1B,IAAM,gBAAA,GAAmB","file":"index.js","sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * @objectstack/spec/contracts/share-link-service\n *\n * Capability-token sharing — \"anyone with the link\" publication of a\n * single record. Complementary to `ISharingService`, which models\n * principal-based grants (share with specific users / teams / roles).\n *\n * Design notes:\n *\n *   1. **Opaque tokens.** A share link is a single random `token`\n *      (>=22 chars from a URL-safe alphabet). Anyone holding the\n *      token can fetch the record subject to `audience` and\n *      `expires_at`. Tokens are *not* derived from the record id;\n *      enumerating record ids reveals nothing.\n *\n *   2. **Per-object opt-in.** `createLink` refuses to mint a token\n *      for an object whose schema does not set `publicSharing.enabled`.\n *      The audience / permission requested must also lie within the\n *      object's `allowedAudiences` / `allowedPermissions` whitelist.\n *\n *   3. **Field-level redaction.** Each resolved link returns a\n *      `redactFields` set (object-default ∪ per-link). The REST gateway\n *      strips these before serialising to the response — the engine\n *      itself sees the raw row so existing hooks fire normally.\n *\n *   4. **No principal expansion.** Holders of a share token are NOT\n *      treated as principals in `sys_record_share`; the token authorises\n *      access only to its single `(object, recordId)` tuple at the\n *      declared `permission` level. This keeps audit trails clean and\n *      prevents lateral movement.\n */\n\n/** Levels selectable when issuing a link. */\nexport type ShareLinkPermission = 'view' | 'comment' | 'edit';\n\n/** Audience gating. */\nexport type ShareLinkAudience = 'public' | 'link_only' | 'signed_in' | 'email';\n\n/** Persisted shape — mirrors `sys_share_link` columns 1:1. */\nexport interface ShareLink {\n  id: string;\n  /** Opaque URL-safe token. Always present; the only secret. */\n  token: string;\n  object_name: string;\n  record_id: string;\n  permission: ShareLinkPermission;\n  audience: ShareLinkAudience;\n  /** ISO timestamp; null means no expiry. */\n  expires_at?: string | null;\n  /** When `audience='email'`, the allow-listed addresses (lowercased). */\n  email_allowlist?: string[] | null;\n  /** Optional argon2/bcrypt hash; UI prompts for a password when set. */\n  password_hash?: string | null;\n  /** Per-link extra redactions, layered on top of the object-default set. */\n  redact_fields?: string[] | null;\n  /** Free-text shown in the share dialog (e.g. \"Q3 contract for ACME\"). */\n  label?: string | null;\n  /** When set, the link is revoked and `resolveToken` returns null. */\n  revoked_at?: string | null;\n  created_by?: string | null;\n  created_at?: string;\n  last_used_at?: string | null;\n  use_count?: number;\n}\n\n/** Input for {@link IShareLinkService.createLink}. */\nexport interface CreateShareLinkInput {\n  object: string;\n  recordId: string;\n  permission?: ShareLinkPermission;\n  audience?: ShareLinkAudience;\n  /** ISO timestamp or relative duration string (\"7d\", \"24h\") — service normalises. */\n  expiresAt?: string | null;\n  emailAllowlist?: string[];\n  /** Plain-text password; service hashes before persisting. */\n  password?: string;\n  /** Per-link redactions in addition to the object default. */\n  redactFields?: string[];\n  label?: string;\n}\n\n/** Filter for {@link IShareLinkService.listLinks}. */\nexport interface ListShareLinksFilter {\n  object?: string;\n  recordId?: string;\n  createdBy?: string;\n  includeRevoked?: boolean;\n}\n\n/** Outcome of resolving a token via the public endpoint. */\nexport interface ResolveShareLinkResult {\n  link: ShareLink;\n  /** Effective fields removed from the response (object default ∪ per-link). */\n  redactFields: string[];\n}\n\n/** Minimal context interface — kept compatible with `SharingExecutionContext`. */\nexport interface ShareLinkExecutionContext {\n  userId?: string;\n  tenantId?: string;\n  isSystem?: boolean;\n}\n\n/**\n * Default implementation lives in `@objectstack/plugin-sharing`.\n *\n * Implementations MUST treat `context.isSystem === true` as a bypass\n * (skip the per-object opt-in check) so platform bootstrappers can seed\n * demo links.\n */\nexport interface IShareLinkService {\n  /** Mint a new link. Throws when the object is not opt-in or limits are exceeded. */\n  createLink(input: CreateShareLinkInput, context: ShareLinkExecutionContext): Promise<ShareLink>;\n\n  /** Mark a link as revoked. No-op when already revoked or not found. */\n  revokeLink(idOrToken: string, context: ShareLinkExecutionContext): Promise<void>;\n\n  /** List links for a record, an object, or a creator. */\n  listLinks(filter: ListShareLinksFilter, context: ShareLinkExecutionContext): Promise<ShareLink[]>;\n\n  /**\n   * Resolve a token at request-handling time. Returns null when the\n   * token does not exist, is revoked, expired, or fails the audience\n   * check. Increments `use_count` / `last_used_at` as a side effect.\n   *\n   * @param token  raw token from the URL / cookie\n   * @param probe  contextual gates the caller has already evaluated\n   *               (e.g. signed-in user, recipient email, supplied\n   *               password)\n   */\n  resolveToken(\n    token: string,\n    probe?: {\n      signedInUserId?: string;\n      recipientEmail?: string;\n      providedPassword?: string;\n    },\n  ): Promise<ResolveShareLinkResult | null>;\n}\n\n/** Service-registry key — keep in sync with the SharingPlugin registration. */\nexport const SHARE_LINK_SERVICE = 'shareLinks' as const;\n","// 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","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `IEmbedder` — protocol-level contract for text → vector providers.\n *\n * Implemented by embedder plugins (`@objectstack/embedder-openai`,\n * `@objectstack/embedder-ollama`, `@objectstack/embedder-transformers-js`,\n * …) and consumed by every knowledge adapter that needs to compute\n * vectors (e.g. `@objectstack/knowledge-turso`,\n * `@objectstack/knowledge-sqlite-vec`).\n *\n * The surface is deliberately minimal so the same protocol covers\n * cloud APIs (OpenAI, 阿里通义, 智谱, 硅基流动, Doubao, …), local\n * Ollama daemons, in-process WASM/ONNX runtimes, and any OpenAI-shape\n * compatible endpoint. Implementations are responsible for batching,\n * retry, and rate-limit handling against their upstream.\n *\n * Conventions:\n *  - Output order MUST match input order exactly.\n *  - Vectors SHOULD be L2-normalised so downstream cosine == dot.\n *  - `dimensions` MUST be stable for the lifetime of the instance —\n *    knowledge adapters size their vector columns from this value.\n *\n * See `content/docs/protocol/knowledge.mdx`.\n */\nexport interface IEmbedder {\n  /** Stable id for logs and diagnostics (e.g. `'openai'`, `'ollama'`). */\n  readonly id: string;\n  /**\n   * Output vector dimensionality. Knowledge adapters use this to size\n   * their fixed-width vector columns / index parameters.\n   */\n  readonly dimensions: number;\n  /**\n   * Embed a batch of strings. Output order matches input order.\n   * Implementations SHOULD handle empty input by returning `[]`.\n   */\n  embed(texts: string[]): Promise<number[][]>;\n}\n\n/**\n * DI service token for the kernel-registered `IEmbedder` instance.\n *\n * Plugins that need an embedder (e.g. `@objectstack/knowledge-turso`,\n * `@objectstack/knowledge-sqlite-vec`) SHOULD prefer resolving this\n * service over taking the embedder as a constructor option, so\n * operators can configure the embedder once (in `Settings → AI &\n * Embedder`) and have every knowledge adapter pick it up.\n *\n * Registered by `@objectstack/service-ai` when the operator selects a\n * non-`none` embedder provider in settings. If absent, knowledge\n * adapters fall back to their constructor-supplied embedder (or refuse\n * to start).\n */\nexport const EMBEDDER_SERVICE = 'embedder' as const;\n"]}

package/dist/contracts/index.mjs

@@ -1,9 +1,12 @@
+// src/contracts/share-link-service.ts
+var SHARE_LINK_SERVICE = "shareLinks";
+
 // src/contracts/knowledge-service.ts
 var KNOWLEDGE_SERVICE = "knowledge";
 
 // src/contracts/embedder.ts
 var EMBEDDER_SERVICE = "embedder";
 
-export { EMBEDDER_SERVICE, KNOWLEDGE_SERVICE };
+export { EMBEDDER_SERVICE, KNOWLEDGE_SERVICE, SHARE_LINK_SERVICE };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/contracts/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/contracts/knowledge-service.ts","../../src/contracts/embedder.ts"],"names":[],"mappings":";AAgHO,IAAM,iBAAA,GAAoB;;;AC1D1B,IAAM,gBAAA,GAAmB","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","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `IEmbedder` — protocol-level contract for text → vector providers.\n *\n * Implemented by embedder plugins (`@objectstack/embedder-openai`,\n * `@objectstack/embedder-ollama`, `@objectstack/embedder-transformers-js`,\n * …) and consumed by every knowledge adapter that needs to compute\n * vectors (e.g. `@objectstack/knowledge-turso`,\n * `@objectstack/knowledge-sqlite-vec`).\n *\n * The surface is deliberately minimal so the same protocol covers\n * cloud APIs (OpenAI, 阿里通义, 智谱, 硅基流动, Doubao, …), local\n * Ollama daemons, in-process WASM/ONNX runtimes, and any OpenAI-shape\n * compatible endpoint. Implementations are responsible for batching,\n * retry, and rate-limit handling against their upstream.\n *\n * Conventions:\n *  - Output order MUST match input order exactly.\n *  - Vectors SHOULD be L2-normalised so downstream cosine == dot.\n *  - `dimensions` MUST be stable for the lifetime of the instance —\n *    knowledge adapters size their vector columns from this value.\n *\n * See `content/docs/protocol/knowledge.mdx`.\n */\nexport interface IEmbedder {\n  /** Stable id for logs and diagnostics (e.g. `'openai'`, `'ollama'`). */\n  readonly id: string;\n  /**\n   * Output vector dimensionality. Knowledge adapters use this to size\n   * their fixed-width vector columns / index parameters.\n   */\n  readonly dimensions: number;\n  /**\n   * Embed a batch of strings. Output order matches input order.\n   * Implementations SHOULD handle empty input by returning `[]`.\n   */\n  embed(texts: string[]): Promise<number[][]>;\n}\n\n/**\n * DI service token for the kernel-registered `IEmbedder` instance.\n *\n * Plugins that need an embedder (e.g. `@objectstack/knowledge-turso`,\n * `@objectstack/knowledge-sqlite-vec`) SHOULD prefer resolving this\n * service over taking the embedder as a constructor option, so\n * operators can configure the embedder once (in `Settings → AI &\n * Embedder`) and have every knowledge adapter pick it up.\n *\n * Registered by `@objectstack/service-ai` when the operator selects a\n * non-`none` embedder provider in settings. If absent, knowledge\n * adapters fall back to their constructor-supplied embedder (or refuse\n * to start).\n */\nexport const EMBEDDER_SERVICE = 'embedder' as const;\n"]}
+{"version":3,"sources":["../../src/contracts/share-link-service.ts","../../src/contracts/knowledge-service.ts","../../src/contracts/embedder.ts"],"names":[],"mappings":";AA+IO,IAAM,kBAAA,GAAqB;;;AC/B3B,IAAM,iBAAA,GAAoB;;;AC1D1B,IAAM,gBAAA,GAAmB","file":"index.mjs","sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * @objectstack/spec/contracts/share-link-service\n *\n * Capability-token sharing — \"anyone with the link\" publication of a\n * single record. Complementary to `ISharingService`, which models\n * principal-based grants (share with specific users / teams / roles).\n *\n * Design notes:\n *\n *   1. **Opaque tokens.** A share link is a single random `token`\n *      (>=22 chars from a URL-safe alphabet). Anyone holding the\n *      token can fetch the record subject to `audience` and\n *      `expires_at`. Tokens are *not* derived from the record id;\n *      enumerating record ids reveals nothing.\n *\n *   2. **Per-object opt-in.** `createLink` refuses to mint a token\n *      for an object whose schema does not set `publicSharing.enabled`.\n *      The audience / permission requested must also lie within the\n *      object's `allowedAudiences` / `allowedPermissions` whitelist.\n *\n *   3. **Field-level redaction.** Each resolved link returns a\n *      `redactFields` set (object-default ∪ per-link). The REST gateway\n *      strips these before serialising to the response — the engine\n *      itself sees the raw row so existing hooks fire normally.\n *\n *   4. **No principal expansion.** Holders of a share token are NOT\n *      treated as principals in `sys_record_share`; the token authorises\n *      access only to its single `(object, recordId)` tuple at the\n *      declared `permission` level. This keeps audit trails clean and\n *      prevents lateral movement.\n */\n\n/** Levels selectable when issuing a link. */\nexport type ShareLinkPermission = 'view' | 'comment' | 'edit';\n\n/** Audience gating. */\nexport type ShareLinkAudience = 'public' | 'link_only' | 'signed_in' | 'email';\n\n/** Persisted shape — mirrors `sys_share_link` columns 1:1. */\nexport interface ShareLink {\n  id: string;\n  /** Opaque URL-safe token. Always present; the only secret. */\n  token: string;\n  object_name: string;\n  record_id: string;\n  permission: ShareLinkPermission;\n  audience: ShareLinkAudience;\n  /** ISO timestamp; null means no expiry. */\n  expires_at?: string | null;\n  /** When `audience='email'`, the allow-listed addresses (lowercased). */\n  email_allowlist?: string[] | null;\n  /** Optional argon2/bcrypt hash; UI prompts for a password when set. */\n  password_hash?: string | null;\n  /** Per-link extra redactions, layered on top of the object-default set. */\n  redact_fields?: string[] | null;\n  /** Free-text shown in the share dialog (e.g. \"Q3 contract for ACME\"). */\n  label?: string | null;\n  /** When set, the link is revoked and `resolveToken` returns null. */\n  revoked_at?: string | null;\n  created_by?: string | null;\n  created_at?: string;\n  last_used_at?: string | null;\n  use_count?: number;\n}\n\n/** Input for {@link IShareLinkService.createLink}. */\nexport interface CreateShareLinkInput {\n  object: string;\n  recordId: string;\n  permission?: ShareLinkPermission;\n  audience?: ShareLinkAudience;\n  /** ISO timestamp or relative duration string (\"7d\", \"24h\") — service normalises. */\n  expiresAt?: string | null;\n  emailAllowlist?: string[];\n  /** Plain-text password; service hashes before persisting. */\n  password?: string;\n  /** Per-link redactions in addition to the object default. */\n  redactFields?: string[];\n  label?: string;\n}\n\n/** Filter for {@link IShareLinkService.listLinks}. */\nexport interface ListShareLinksFilter {\n  object?: string;\n  recordId?: string;\n  createdBy?: string;\n  includeRevoked?: boolean;\n}\n\n/** Outcome of resolving a token via the public endpoint. */\nexport interface ResolveShareLinkResult {\n  link: ShareLink;\n  /** Effective fields removed from the response (object default ∪ per-link). */\n  redactFields: string[];\n}\n\n/** Minimal context interface — kept compatible with `SharingExecutionContext`. */\nexport interface ShareLinkExecutionContext {\n  userId?: string;\n  tenantId?: string;\n  isSystem?: boolean;\n}\n\n/**\n * Default implementation lives in `@objectstack/plugin-sharing`.\n *\n * Implementations MUST treat `context.isSystem === true` as a bypass\n * (skip the per-object opt-in check) so platform bootstrappers can seed\n * demo links.\n */\nexport interface IShareLinkService {\n  /** Mint a new link. Throws when the object is not opt-in or limits are exceeded. */\n  createLink(input: CreateShareLinkInput, context: ShareLinkExecutionContext): Promise<ShareLink>;\n\n  /** Mark a link as revoked. No-op when already revoked or not found. */\n  revokeLink(idOrToken: string, context: ShareLinkExecutionContext): Promise<void>;\n\n  /** List links for a record, an object, or a creator. */\n  listLinks(filter: ListShareLinksFilter, context: ShareLinkExecutionContext): Promise<ShareLink[]>;\n\n  /**\n   * Resolve a token at request-handling time. Returns null when the\n   * token does not exist, is revoked, expired, or fails the audience\n   * check. Increments `use_count` / `last_used_at` as a side effect.\n   *\n   * @param token  raw token from the URL / cookie\n   * @param probe  contextual gates the caller has already evaluated\n   *               (e.g. signed-in user, recipient email, supplied\n   *               password)\n   */\n  resolveToken(\n    token: string,\n    probe?: {\n      signedInUserId?: string;\n      recipientEmail?: string;\n      providedPassword?: string;\n    },\n  ): Promise<ResolveShareLinkResult | null>;\n}\n\n/** Service-registry key — keep in sync with the SharingPlugin registration. */\nexport const SHARE_LINK_SERVICE = 'shareLinks' as const;\n","// 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","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `IEmbedder` — protocol-level contract for text → vector providers.\n *\n * Implemented by embedder plugins (`@objectstack/embedder-openai`,\n * `@objectstack/embedder-ollama`, `@objectstack/embedder-transformers-js`,\n * …) and consumed by every knowledge adapter that needs to compute\n * vectors (e.g. `@objectstack/knowledge-turso`,\n * `@objectstack/knowledge-sqlite-vec`).\n *\n * The surface is deliberately minimal so the same protocol covers\n * cloud APIs (OpenAI, 阿里通义, 智谱, 硅基流动, Doubao, …), local\n * Ollama daemons, in-process WASM/ONNX runtimes, and any OpenAI-shape\n * compatible endpoint. Implementations are responsible for batching,\n * retry, and rate-limit handling against their upstream.\n *\n * Conventions:\n *  - Output order MUST match input order exactly.\n *  - Vectors SHOULD be L2-normalised so downstream cosine == dot.\n *  - `dimensions` MUST be stable for the lifetime of the instance —\n *    knowledge adapters size their vector columns from this value.\n *\n * See `content/docs/protocol/knowledge.mdx`.\n */\nexport interface IEmbedder {\n  /** Stable id for logs and diagnostics (e.g. `'openai'`, `'ollama'`). */\n  readonly id: string;\n  /**\n   * Output vector dimensionality. Knowledge adapters use this to size\n   * their fixed-width vector columns / index parameters.\n   */\n  readonly dimensions: number;\n  /**\n   * Embed a batch of strings. Output order matches input order.\n   * Implementations SHOULD handle empty input by returning `[]`.\n   */\n  embed(texts: string[]): Promise<number[][]>;\n}\n\n/**\n * DI service token for the kernel-registered `IEmbedder` instance.\n *\n * Plugins that need an embedder (e.g. `@objectstack/knowledge-turso`,\n * `@objectstack/knowledge-sqlite-vec`) SHOULD prefer resolving this\n * service over taking the embedder as a constructor option, so\n * operators can configure the embedder once (in `Settings → AI &\n * Embedder`) and have every knowledge adapter pick it up.\n *\n * Registered by `@objectstack/service-ai` when the operator selects a\n * non-`none` embedder provider in settings. If absent, knowledge\n * adapters fall back to their constructor-supplied embedder (or refuse\n * to start).\n */\nexport const EMBEDDER_SERVICE = 'embedder' as const;\n"]}

package/dist/data/index.d.mts

@@ -2,7 +2,7 @@ import { Q as QueryAST } from '../query.zod-C-iygIgx.mjs';
 export { A as AggregationFunction, a as AggregationNode, b as AggregationNodeSchema, D as DateGranularity, c as DateGranularityValue, F as FieldNodeSchema, d as FullTextSearch, e as FullTextSearchSchema, G as GroupByNode, f as GroupByNodeSchema, J as JoinNode, g as JoinNodeSchema, h as JoinStrategy, i as JoinType, j as QueryInput, k as QuerySchema, S as SortNode, l as SortNodeSchema, W as WindowFunction, m as WindowFunctionNode, n as WindowFunctionNodeSchema, o as WindowSpec, p as WindowSpecSchema } from '../query.zod-C-iygIgx.mjs';
 export { A as ALL_OPERATORS, C as ComparisonOperatorSchema, E as EqualityOperatorSchema, F as FILTER_OPERATORS, a as FieldOperators, b as FieldOperatorsSchema, c as FieldReference, d as FieldReferenceSchema, e as Filter, f as FilterCondition, g as FilterConditionSchema, h as FilterOperatorKey, L as LOGICAL_OPERATORS, i as LogicalOperatorKey, N as NormalizedFilter, j as NormalizedFilterSchema, O as OperatorKey, Q as QueryFilter, k as QueryFilterSchema, R as RangeOperatorSchema, S as Scalar, l as SetOperatorSchema, m as SpecialOperatorSchema, n as StringOperatorSchema, V as VALID_AST_OPERATORS, o as isFilterAST, p as parseFilterAST } from '../filter.zod-DG_Mf2_S.mjs';
 import { z } from 'zod';
-export { A as ApiMethod, a as AsyncValidation, b as AsyncValidationSchema, B as BaseValidationRuleShape, C as CDCConfig, c as CDCConfigSchema, d as ConditionalValidation, e as ConditionalValidationSchema, f as CrossFieldValidation, g as CrossFieldValidationSchema, h as CrudAffordances, i as CustomValidation, j as CustomValidatorSchema, F as FormatValidation, k as FormatValidationSchema, I as IndexSchema, J as JSONValidation, l as JSONValidationSchema, O as ObjectCapabilities, m as ObjectExtension, n as ObjectExtensionSchema, o as ObjectFieldGroup, p as ObjectFieldGroupInput, q as ObjectFieldGroupSchema, r as ObjectIndex, s as ObjectOwnership, t as ObjectOwnershipEnum, u as ObjectSchema, P as PartitioningConfig, v as PartitioningConfigSchema, S as ScriptValidation, w as ScriptValidationSchema, x as SearchConfigSchema, y as ServiceObject, z as ServiceObjectInput, D as SoftDeleteConfig, E as SoftDeleteConfigSchema, G as StateMachineValidation, H as StateMachineValidationSchema, T as TenancyConfig, K as TenancyConfigSchema, U as UniquenessValidation, L as UniquenessValidationSchema, V as ValidationRule, M as ValidationRuleSchema, N as VersioningConfig, Q as VersioningConfigSchema, R as resolveCrudAffordances } from '../object.zod-C1mmiCDL.mjs';
+export { A as ApiMethod, a as AsyncValidation, b as AsyncValidationSchema, B as BaseValidationRuleShape, C as CDCConfig, c as CDCConfigSchema, d as ConditionalValidation, e as ConditionalValidationSchema, f as CrossFieldValidation, g as CrossFieldValidationSchema, h as CrudAffordances, i as CustomValidation, j as CustomValidatorSchema, F as FormatValidation, k as FormatValidationSchema, I as IndexSchema, J as JSONValidation, l as JSONValidationSchema, O as ObjectCapabilities, m as ObjectExtension, n as ObjectExtensionSchema, o as ObjectFieldGroup, p as ObjectFieldGroupInput, q as ObjectFieldGroupSchema, r as ObjectIndex, s as ObjectOwnership, t as ObjectOwnershipEnum, u as ObjectSchema, P as PartitioningConfig, v as PartitioningConfigSchema, S as ScriptValidation, w as ScriptValidationSchema, x as SearchConfigSchema, y as ServiceObject, z as ServiceObjectInput, D as SoftDeleteConfig, E as SoftDeleteConfigSchema, G as StateMachineValidation, H as StateMachineValidationSchema, T as TenancyConfig, K as TenancyConfigSchema, U as UniquenessValidation, L as UniquenessValidationSchema, V as ValidationRule, M as ValidationRuleSchema, N as VersioningConfig, Q as VersioningConfigSchema, R as resolveCrudAffordances } from '../object.zod-CATh64Wi.mjs';
 export { A as Address, a as AddressSchema, C as ComputedFieldCache, b as ComputedFieldCacheSchema, c as CurrencyConfig, d as CurrencyConfigInput, e as CurrencyConfigSchema, f as CurrencyValue, g as CurrencyValueSchema, D as DataQualityRules, h as DataQualityRulesInput, i as DataQualityRulesSchema, F as Field, j as FieldInput, k as FieldSchema, l as FieldType, m as FileAttachmentConfig, n as FileAttachmentConfigInput, o as FileAttachmentConfigSchema, L as LocationCoordinates, p as LocationCoordinatesSchema, S as SelectOption, q as SelectOptionSchema, V as VectorConfig, r as VectorConfigInput, s as VectorConfigSchema } from '../field.zod-BGr7R7KU.mjs';
 export { A as AggregationMetricType, a as AnalyticsQuery, b as AnalyticsQuerySchema, B as BaseEngineOptions, c as BaseEngineOptionsSchema, C as Cube, d as CubeJoin, e as CubeJoinSchema, f as CubeSchema, D as DataEngineAggregateOptions, g as DataEngineAggregateOptionsSchema, h as DataEngineAggregateRequestSchema, i as DataEngineBatchRequestSchema, j as DataEngineContractSchema, k as DataEngineCountOptions, l as DataEngineCountOptionsSchema, m as DataEngineCountRequestSchema, n as DataEngineDeleteOptions, o as DataEngineDeleteOptionsSchema, p as DataEngineDeleteRequestSchema, q as DataEngineExecuteRequestSchema, r as DataEngineFilter, s as DataEngineFilterSchema, t as DataEngineFindOneRequestSchema, u as DataEngineFindRequestSchema, v as DataEngineInsertOptions, w as DataEngineInsertOptionsSchema, x as DataEngineInsertRequestSchema, y as DataEngineQueryOptions, z as DataEngineQueryOptionsSchema, E as DataEngineRequest, F as DataEngineRequestSchema, G as DataEngineSort, H as DataEngineSortSchema, I as DataEngineUpdateOptions, J as DataEngineUpdateOptionsSchema, K as DataEngineUpdateRequestSchema, L as DataEngineVectorFindRequestSchema, M as DataTypeMapping, N as DataTypeMappingSchema, O as Dataset, P as DatasetImportMode, Q as DatasetInput, R as DatasetLoadResult, S as DatasetLoadResultSchema, T as DatasetMode, U as DatasetSchema, V as Dimension, W as DimensionSchema, X as DimensionType, Y as DriverCapabilities, Z as DriverCapabilitiesSchema, _ as DriverConfig, $ as DriverConfigSchema, a0 as DriverInterface, a1 as DriverInterfaceSchema, a2 as DriverOptions, a3 as DriverOptionsSchema, a4 as EngineAggregateOptions, a5 as EngineAggregateOptionsSchema, a6 as EngineCountOptions, a7 as EngineCountOptionsSchema, a8 as EngineDeleteOptions, a9 as EngineDeleteOptionsSchema, aa as EngineQueryOptions, ab as EngineQueryOptionsSchema, ac as EngineUpdateOptions, ad as EngineUpdateOptionsSchema, ae as FeedActor, af as FeedActorSchema, ag as FeedFilterMode, ah as FeedItem, ai as FeedItemSchema, aj as FeedItemType, ak as FeedVisibility, al as FieldChangeEntry, am as FieldChangeEntrySchema, an as Mention, ao as MentionSchema, ap as Metric, aq as MetricSchema, ar as NotificationChannel, as as ObjectDependencyGraph, at as ObjectDependencyGraphSchema, au as ObjectDependencyNode, av as ObjectDependencyNodeSchema, aw as PoolConfig, ax as PoolConfigSchema, ay as Reaction, az as ReactionSchema, aA as RecordSubscription, aB as RecordSubscriptionSchema, aC as ReferenceResolution, aD as ReferenceResolutionError, aE as ReferenceResolutionErrorSchema, aF as ReferenceResolutionSchema, aG as SQLDialect, aH as SQLDialectSchema, aI as SQLDriverConfig, aJ as SQLDriverConfigSchema, aK as SQLiteAlterTableLimitations, aL as SQLiteDataTypeMappingDefaults, aM as SSLConfig, aN as SSLConfigSchema, aO as SeedLoaderConfig, aP as SeedLoaderConfigInput, aQ as SeedLoaderConfigSchema, aR as SeedLoaderRequest, aS as SeedLoaderRequestInput, aT as SeedLoaderRequestSchema, aU as SeedLoaderResult, aV as SeedLoaderResultSchema, aW as SubscriptionEventType, aX as TimeUpdateInterval, aY as defineDataset } from '../subscription.zod-MSheiEQT.mjs';
 import '../state-machine.zod-BNanU03M.mjs';

package/dist/data/index.d.ts

@@ -2,7 +2,7 @@ import { Q as QueryAST } from '../query.zod-CGnJOIQH.js';
 export { A as AggregationFunction, a as AggregationNode, b as AggregationNodeSchema, D as DateGranularity, c as DateGranularityValue, F as FieldNodeSchema, d as FullTextSearch, e as FullTextSearchSchema, G as GroupByNode, f as GroupByNodeSchema, J as JoinNode, g as JoinNodeSchema, h as JoinStrategy, i as JoinType, j as QueryInput, k as QuerySchema, S as SortNode, l as SortNodeSchema, W as WindowFunction, m as WindowFunctionNode, n as WindowFunctionNodeSchema, o as WindowSpec, p as WindowSpecSchema } from '../query.zod-CGnJOIQH.js';
 export { A as ALL_OPERATORS, C as ComparisonOperatorSchema, E as EqualityOperatorSchema, F as FILTER_OPERATORS, a as FieldOperators, b as FieldOperatorsSchema, c as FieldReference, d as FieldReferenceSchema, e as Filter, f as FilterCondition, g as FilterConditionSchema, h as FilterOperatorKey, L as LOGICAL_OPERATORS, i as LogicalOperatorKey, N as NormalizedFilter, j as NormalizedFilterSchema, O as OperatorKey, Q as QueryFilter, k as QueryFilterSchema, R as RangeOperatorSchema, S as Scalar, l as SetOperatorSchema, m as SpecialOperatorSchema, n as StringOperatorSchema, V as VALID_AST_OPERATORS, o as isFilterAST, p as parseFilterAST } from '../filter.zod-DG_Mf2_S.js';
 import { z } from 'zod';
-export { A as ApiMethod, a as AsyncValidation, b as AsyncValidationSchema, B as BaseValidationRuleShape, C as CDCConfig, c as CDCConfigSchema, d as ConditionalValidation, e as ConditionalValidationSchema, f as CrossFieldValidation, g as CrossFieldValidationSchema, h as CrudAffordances, i as CustomValidation, j as CustomValidatorSchema, F as FormatValidation, k as FormatValidationSchema, I as IndexSchema, J as JSONValidation, l as JSONValidationSchema, O as ObjectCapabilities, m as ObjectExtension, n as ObjectExtensionSchema, o as ObjectFieldGroup, p as ObjectFieldGroupInput, q as ObjectFieldGroupSchema, r as ObjectIndex, s as ObjectOwnership, t as ObjectOwnershipEnum, u as ObjectSchema, P as PartitioningConfig, v as PartitioningConfigSchema, S as ScriptValidation, w as ScriptValidationSchema, x as SearchConfigSchema, y as ServiceObject, z as ServiceObjectInput, D as SoftDeleteConfig, E as SoftDeleteConfigSchema, G as StateMachineValidation, H as StateMachineValidationSchema, T as TenancyConfig, K as TenancyConfigSchema, U as UniquenessValidation, L as UniquenessValidationSchema, V as ValidationRule, M as ValidationRuleSchema, N as VersioningConfig, Q as VersioningConfigSchema, R as resolveCrudAffordances } from '../object.zod-D4gYbFv4.js';
+export { A as ApiMethod, a as AsyncValidation, b as AsyncValidationSchema, B as BaseValidationRuleShape, C as CDCConfig, c as CDCConfigSchema, d as ConditionalValidation, e as ConditionalValidationSchema, f as CrossFieldValidation, g as CrossFieldValidationSchema, h as CrudAffordances, i as CustomValidation, j as CustomValidatorSchema, F as FormatValidation, k as FormatValidationSchema, I as IndexSchema, J as JSONValidation, l as JSONValidationSchema, O as ObjectCapabilities, m as ObjectExtension, n as ObjectExtensionSchema, o as ObjectFieldGroup, p as ObjectFieldGroupInput, q as ObjectFieldGroupSchema, r as ObjectIndex, s as ObjectOwnership, t as ObjectOwnershipEnum, u as ObjectSchema, P as PartitioningConfig, v as PartitioningConfigSchema, S as ScriptValidation, w as ScriptValidationSchema, x as SearchConfigSchema, y as ServiceObject, z as ServiceObjectInput, D as SoftDeleteConfig, E as SoftDeleteConfigSchema, G as StateMachineValidation, H as StateMachineValidationSchema, T as TenancyConfig, K as TenancyConfigSchema, U as UniquenessValidation, L as UniquenessValidationSchema, V as ValidationRule, M as ValidationRuleSchema, N as VersioningConfig, Q as VersioningConfigSchema, R as resolveCrudAffordances } from '../object.zod-B2nzURDy.js';
 export { A as Address, a as AddressSchema, C as ComputedFieldCache, b as ComputedFieldCacheSchema, c as CurrencyConfig, d as CurrencyConfigInput, e as CurrencyConfigSchema, f as CurrencyValue, g as CurrencyValueSchema, D as DataQualityRules, h as DataQualityRulesInput, i as DataQualityRulesSchema, F as Field, j as FieldInput, k as FieldSchema, l as FieldType, m as FileAttachmentConfig, n as FileAttachmentConfigInput, o as FileAttachmentConfigSchema, L as LocationCoordinates, p as LocationCoordinatesSchema, S as SelectOption, q as SelectOptionSchema, V as VectorConfig, r as VectorConfigInput, s as VectorConfigSchema } from '../field.zod-BGr7R7KU.js';
 export { A as AggregationMetricType, a as AnalyticsQuery, b as AnalyticsQuerySchema, B as BaseEngineOptions, c as BaseEngineOptionsSchema, C as Cube, d as CubeJoin, e as CubeJoinSchema, f as CubeSchema, D as DataEngineAggregateOptions, g as DataEngineAggregateOptionsSchema, h as DataEngineAggregateRequestSchema, i as DataEngineBatchRequestSchema, j as DataEngineContractSchema, k as DataEngineCountOptions, l as DataEngineCountOptionsSchema, m as DataEngineCountRequestSchema, n as DataEngineDeleteOptions, o as DataEngineDeleteOptionsSchema, p as DataEngineDeleteRequestSchema, q as DataEngineExecuteRequestSchema, r as DataEngineFilter, s as DataEngineFilterSchema, t as DataEngineFindOneRequestSchema, u as DataEngineFindRequestSchema, v as DataEngineInsertOptions, w as DataEngineInsertOptionsSchema, x as DataEngineInsertRequestSchema, y as DataEngineQueryOptions, z as DataEngineQueryOptionsSchema, E as DataEngineRequest, F as DataEngineRequestSchema, G as DataEngineSort, H as DataEngineSortSchema, I as DataEngineUpdateOptions, J as DataEngineUpdateOptionsSchema, K as DataEngineUpdateRequestSchema, L as DataEngineVectorFindRequestSchema, M as DataTypeMapping, N as DataTypeMappingSchema, O as Dataset, P as DatasetImportMode, Q as DatasetInput, R as DatasetLoadResult, S as DatasetLoadResultSchema, T as DatasetMode, U as DatasetSchema, V as Dimension, W as DimensionSchema, X as DimensionType, Y as DriverCapabilities, Z as DriverCapabilitiesSchema, _ as DriverConfig, $ as DriverConfigSchema, a0 as DriverInterface, a1 as DriverInterfaceSchema, a2 as DriverOptions, a3 as DriverOptionsSchema, a4 as EngineAggregateOptions, a5 as EngineAggregateOptionsSchema, a6 as EngineCountOptions, a7 as EngineCountOptionsSchema, a8 as EngineDeleteOptions, a9 as EngineDeleteOptionsSchema, aa as EngineQueryOptions, ab as EngineQueryOptionsSchema, ac as EngineUpdateOptions, ad as EngineUpdateOptionsSchema, ae as FeedActor, af as FeedActorSchema, ag as FeedFilterMode, ah as FeedItem, ai as FeedItemSchema, aj as FeedItemType, ak as FeedVisibility, al as FieldChangeEntry, am as FieldChangeEntrySchema, an as Mention, ao as MentionSchema, ap as Metric, aq as MetricSchema, ar as NotificationChannel, as as ObjectDependencyGraph, at as ObjectDependencyGraphSchema, au as ObjectDependencyNode, av as ObjectDependencyNodeSchema, aw as PoolConfig, ax as PoolConfigSchema, ay as Reaction, az as ReactionSchema, aA as RecordSubscription, aB as RecordSubscriptionSchema, aC as ReferenceResolution, aD as ReferenceResolutionError, aE as ReferenceResolutionErrorSchema, aF as ReferenceResolutionSchema, aG as SQLDialect, aH as SQLDialectSchema, aI as SQLDriverConfig, aJ as SQLDriverConfigSchema, aK as SQLiteAlterTableLimitations, aL as SQLiteDataTypeMappingDefaults, aM as SSLConfig, aN as SSLConfigSchema, aO as SeedLoaderConfig, aP as SeedLoaderConfigInput, aQ as SeedLoaderConfigSchema, aR as SeedLoaderRequest, aS as SeedLoaderRequestInput, aT as SeedLoaderRequestSchema, aU as SeedLoaderResult, aV as SeedLoaderResultSchema, aW as SubscriptionEventType, aX as TimeUpdateInterval, aY as defineDataset } from '../subscription.zod-CBBzN0Tf.js';
 import '../state-machine.zod-BNanU03M.js';

package/dist/data/index.js

@@ -2313,7 +2313,8 @@ var ObjectSchemaBase = zod.z.object({
    * declare them per-object (Salesforce-style). Currently injected:
    *
    *   - `organization_id` — `lookup → sys_organization`. Injected only when
-   *     the kernel runs in multi-tenant mode (`OS_MULTI_TENANT !== 'false'`).
+   *     the kernel runs in multi-tenant mode (`OS_MULTI_TENANT === 'true'`;
+   *     default is off — single-tenant).
    *     Required for the default `tenant_isolation` RLS policy and the
    *     SecurityPlugin's auto-fill on insert to take effect.
    *
@@ -2449,6 +2450,57 @@ var ObjectSchemaBase = zod.z.object({
   recordTypes: zod.z.array(zod.z.string()).optional().describe("Record type names for this object"),
   /** Sharing Model */
   sharingModel: zod.z.enum(["private", "read", "read_write", "full"]).optional().describe("Default sharing model"),
+  /**
+   * Public Share-Link Policy
+   *
+   * Opt-in declaration that records of this object MAY be published via
+   * an opaque capability token (Notion / Google Docs / Figma "anyone with
+   * the link" style). When omitted or `enabled:false`, the platform
+   * refuses to create share-link rows for this object — independent of
+   * any permission the caller holds.
+   *
+   * Distinct from {@link sharingModel}, which governs *principal-based*
+   * sharing (share with specific users / teams / roles). A single object
+   * can opt into both: principals get full edit, link recipients get
+   * read-only with redaction.
+   *
+   * Defaults are conservative: when `enabled:true` and no other field is
+   * provided, the plugin allows `link_only` audience + `view` permission
+   * (the safest combination — caller still needs the URL to access).
+   *
+   * @see packages/plugins/plugin-sharing/src/share-link-service.ts
+   */
+  publicSharing: zod.z.object({
+    /** Master switch. When false (default), no share links can be issued for this object. */
+    enabled: zod.z.boolean().default(false).describe("Allow records of this object to be published via share link"),
+    /**
+     * Audiences the platform will accept when issuing a link.
+     * - `public`       — search engines may index; no token check (rare)
+     * - `link_only`    — anyone holding the token (default)
+     * - `signed_in`    — token + an authenticated session of any tenant user
+     * - `email`        — token + recipient's email matches an allowlist
+     */
+    allowedAudiences: zod.z.array(zod.z.enum(["public", "link_only", "signed_in", "email"])).optional().describe("Audiences callers may select when creating a link"),
+    /** Permission levels callers may grant via a link. Defaults to `['view']`. */
+    allowedPermissions: zod.z.array(zod.z.enum(["view", "comment", "edit"])).optional().describe("Permission levels selectable on the share dialog"),
+    /** Hard cap on requested expiry, in days. Links with `expires_at` further out are rejected. */
+    maxExpiryDays: zod.z.number().int().positive().optional().describe("Reject links with expiry beyond this many days"),
+    /**
+     * Fields stripped from every response served via a share token,
+     * regardless of audience. Use for prompts, raw model output,
+     * internal metadata, PII, etc. The owner's normal API access is
+     * unaffected — redaction is applied only when the request principal
+     * is `kind:'share-link'`.
+     */
+    redactFields: zod.z.array(zod.z.string()).optional().describe("Field names removed from records served via a share token"),
+    /**
+     * Optional CEL/JSONLogic predicate evaluated against the candidate
+     * record when a link is created. When the predicate returns false,
+     * the create call fails with 422 (e.g. "draft records cannot be
+     * shared"). Evaluator is the same one used by sharing rules.
+     */
+    eligibility: zod.z.string().optional().describe("CEL expression that must evaluate to true on the target record")
+  }).optional().describe("Public share-link policy (Notion/Figma-style link sharing)"),
   /** Key Prefix */
   keyPrefix: zod.z.string().max(5).optional().describe('Short prefix for record IDs (e.g., "001" for Account)'),
   /**