diff --git a/.changeset/protocol-segment-interfaces.md b/.changeset/protocol-segment-interfaces.md new file mode 100644 index 0000000000..093e314a7f --- /dev/null +++ b/.changeset/protocol-segment-interfaces.md @@ -0,0 +1,9 @@ +--- +'@objectstack/spec': minor +--- + +Segment `ObjectStackProtocol` into per-domain protocol interfaces (ADR-0076 D9) + +`ObjectStackProtocol` was a single 70-method interface spanning 11 unrelated domains. It is now the **composition** of focused per-domain contracts — `DataProtocol`, `MetadataProtocol`, `AnalyticsProtocol`, `AutomationProtocol`, `PackageProtocol`, `ViewProtocol`, `PermissionProtocol`, `WorkflowProtocol`, `RealtimeProtocol`, `NotificationProtocol`, `AiProtocol`, `I18nProtocol`, `FeedProtocol` — all newly exported. + +`ObjectStackProtocol` now `extends` all of them and is **shape-identical** to the previous flat interface, so every existing implementation/consumer is unaffected (non-breaking). New code should depend on the narrowest slice it needs (e.g. `DataProtocol`). Per ADR-0076 D9 (rev.7) the composed union is transitional; capability availability is provided at runtime by the discovery `services` registry. diff --git a/packages/spec/api-surface.json b/packages/spec/api-surface.json index f55cb6d72f..283bbed614 100644 --- a/packages/spec/api-surface.json +++ b/packages/spec/api-surface.json @@ -2050,6 +2050,7 @@ "AiNlqRequestSchema (const)", "AiNlqResponse (type)", "AiNlqResponseSchema (const)", + "AiProtocol (interface)", "AiSuggestRequest (type)", "AiSuggestRequestSchema (const)", "AiSuggestResponse (type)", @@ -2057,6 +2058,7 @@ "AnalyticsEndpoint (type)", "AnalyticsMetadataResponse (type)", "AnalyticsMetadataResponseSchema (const)", + "AnalyticsProtocol (interface)", "AnalyticsQueryRequest (type)", "AnalyticsQueryRequestSchema (const)", "AnalyticsResultResponseSchema (const)", @@ -2121,6 +2123,7 @@ "AutomationApiErrorCode (type)", "AutomationFlowPathParams (type)", "AutomationFlowPathParamsSchema (const)", + "AutomationProtocol (interface)", "AutomationRunPathParams (type)", "AutomationRunPathParamsSchema (const)", "AutomationTriggerRequest (type)", @@ -2241,6 +2244,7 @@ "DataEventType (type)", "DataLoaderConfig (type)", "DataLoaderConfigSchema (const)", + "DataProtocol (interface)", "DeduplicationStrategy (type)", "DeleteDataRequest (type)", "DeleteDataRequestSchema (const)", @@ -2359,6 +2363,7 @@ "FeedListFilterType (const)", "FeedPathParams (type)", "FeedPathParamsSchema (const)", + "FeedProtocol (interface)", "FeedUnsubscribeRequest (type)", "FeedUnsubscribeRequestSchema (const)", "FieldError (type)", @@ -2527,6 +2532,7 @@ "HttpFindQueryParamsSchema (const)", "HttpMethod (type)", "HttpStatusCode (type)", + "I18nProtocol (interface)", "IdRequest (type)", "IdRequestSchema (const)", "ImportValidationConfig (type)", @@ -2625,6 +2631,7 @@ "MetadataOverlayResponse (type)", "MetadataOverlayResponseSchema (const)", "MetadataOverlaySaveRequestSchema (const)", + "MetadataProtocol (interface)", "MetadataQueryRequestSchema (const)", "MetadataQueryResponse (type)", "MetadataQueryResponseSchema (const)", @@ -2644,6 +2651,7 @@ "NotificationPreferences (type)", "NotificationPreferencesInput (type)", "NotificationPreferencesSchema (const)", + "NotificationProtocol (interface)", "NotificationSchema (const)", "OData (const)", "ODataConfig (type)", @@ -2691,6 +2699,7 @@ "PackageInstallResponseSchema (const)", "PackagePathParams (type)", "PackagePathParamsSchema (const)", + "PackageProtocol (interface)", "PackageRollbackRequest (type)", "PackageRollbackRequestSchema (const)", "PackageRollbackResponse (type)", @@ -2700,6 +2709,7 @@ "PackageUpgradeRequestSchema (const)", "PackageUpgradeResponse (type)", "PackageUpgradeResponseSchema (const)", + "PermissionProtocol (interface)", "PinFeedItemRequest (type)", "PinFeedItemRequestSchema (const)", "PinFeedItemResponse (type)", @@ -2739,6 +2749,7 @@ "RealtimeEventType (type)", "RealtimePresence (type)", "RealtimePresenceSchema (const)", + "RealtimeProtocol (interface)", "RealtimeRecordAction (type)", "RealtimeSubscribeRequest (type)", "RealtimeSubscribeRequestSchema (const)", @@ -2945,6 +2956,7 @@ "VersioningConfigInput (type)", "VersioningConfigSchema (const)", "VersioningStrategy (type)", + "ViewProtocol (interface)", "WebSocketConfig (type)", "WebSocketConfigSchema (const)", "WebSocketEvent (type)", @@ -2961,6 +2973,7 @@ "WebhookEventSchema (const)", "WellKnownCapabilities (type)", "WellKnownCapabilitiesSchema (const)", + "WorkflowProtocol (interface)", "WorkflowState (type)", "WorkflowStateSchema (const)", "WorkflowTransitionRequest (type)", diff --git a/packages/spec/src/api/protocol.zod.ts b/packages/spec/src/api/protocol.zod.ts index 6fb43032d2..d180f0f222 100644 --- a/packages/spec/src/api/protocol.zod.ts +++ b/packages/spec/src/api/protocol.zod.ts @@ -1376,7 +1376,34 @@ export type ObjectStackProtocolZod = z.infer; * The Zod schema (ObjectStackProtocolSchema) is used for runtime validation, * while this interface provides compile-time type safety for implementations. */ -export interface ObjectStackProtocol { +// ───────────────────────────────────────────────────────────────────────────── +// Protocol contracts, segmented per domain (ADR-0076 D9). +// +// `ObjectStackProtocol` (below) is the composition of these per-domain contracts +// and is shape-identical to the historical flat interface — a back-compat alias. +// New code should depend on the narrowest slice it needs (e.g. `DataProtocol`). +// Per ADR-0076 D9 (rev.7) the union is transitional; the end-state dissolves it +// in favour of independent domain protocols + the discovery `services` registry. +// ───────────────────────────────────────────────────────────────────────────── + +/** Business-data CRUD + batch operations (thin wire-normalizers over the engine). */ +export interface DataProtocol { + // Data Operations (core) + findData(request: FindDataRequest): Promise; + getData(request: GetDataRequest): Promise; + createData(request: CreateDataRequest): Promise; + updateData(request: UpdateDataRequest): Promise; + deleteData(request: DeleteDataRequest): Promise; + + // Batch Operations (optional) + batchData?(request: BatchDataRequest): Promise; + createManyData?(request: CreateManyDataRequest): Promise; + updateManyData?(request: UpdateManyDataRequest): Promise; + deleteManyData?(request: DeleteManyDataRequest): Promise; +} + +/** Discovery + metadata (sys_metadata) management. */ +export interface MetadataProtocol { // Discovery & Metadata (core) getDiscovery(request?: GetDiscoveryRequest): Promise; getMetaTypes(request?: GetMetaTypesRequest): Promise; @@ -1392,61 +1419,64 @@ export interface ObjectStackProtocol { deleteMetaItem?(request: DeleteMetaItemRequest): Promise; getMetaItemCached?(request: GetMetaItemCachedRequest): Promise; getUiView?(request: GetUiViewRequest): Promise; - - // Analytics (optional) +} + +/** Analytics (optional). */ +export interface AnalyticsProtocol { analyticsQuery?(request: AnalyticsQueryRequest): Promise; getAnalyticsMeta?(request: GetAnalyticsMetaRequest): Promise; +} - // Automation (optional) +/** Automation (optional). */ +export interface AutomationProtocol { triggerAutomation?(request: AutomationTriggerRequest): Promise; +} - // Package Management (optional) +/** Package lifecycle (optional). */ +export interface PackageProtocol { listPackages?(request: ListPackagesRequest): Promise; getPackage?(request: GetPackageRequest): Promise; installPackage?(request: InstallPackageRequest): Promise; uninstallPackage?(request: UninstallPackageRequest): Promise; enablePackage?(request: EnablePackageRequest): Promise; disablePackage?(request: DisablePackageRequest): Promise; +} - // Data Operations (core) - findData(request: FindDataRequest): Promise; - getData(request: GetDataRequest): Promise; - createData(request: CreateDataRequest): Promise; - updateData(request: UpdateDataRequest): Promise; - deleteData(request: DeleteDataRequest): Promise; - - // Batch Operations (optional) - batchData?(request: BatchDataRequest): Promise; - createManyData?(request: CreateManyDataRequest): Promise; - updateManyData?(request: UpdateManyDataRequest): Promise; - deleteManyData?(request: DeleteManyDataRequest): Promise; - - // View Management (optional) +/** View management (optional). */ +export interface ViewProtocol { listViews?(request: ListViewsRequest): Promise; getView?(request: GetViewRequest): Promise; createView?(request: CreateViewRequest): Promise; updateView?(request: UpdateViewRequest): Promise; deleteView?(request: DeleteViewRequest): Promise; +} - // Permissions (optional) +/** Permissions (optional). */ +export interface PermissionProtocol { checkPermission?(request: CheckPermissionRequest): Promise; getObjectPermissions?(request: GetObjectPermissionsRequest): Promise; getEffectivePermissions?(request: GetEffectivePermissionsRequest): Promise; +} - // Workflows (optional) +/** Workflows (optional). */ +export interface WorkflowProtocol { getWorkflowConfig?(request: GetWorkflowConfigRequest): Promise; getWorkflowState?(request: GetWorkflowStateRequest): Promise; workflowTransition?(request: WorkflowTransitionRequest): Promise; +} - // Realtime (optional) +/** Realtime / presence (optional). */ +export interface RealtimeProtocol { realtimeConnect?(request: RealtimeConnectRequest): Promise; realtimeDisconnect?(request: RealtimeDisconnectRequest): Promise; realtimeSubscribe?(request: RealtimeSubscribeRequest): Promise; realtimeUnsubscribe?(request: RealtimeUnsubscribeRequest): Promise; setPresence?(request: SetPresenceRequest): Promise; getPresence?(request: GetPresenceRequest): Promise; +} - // Notifications (optional) +/** Notifications (optional). */ +export interface NotificationProtocol { registerDevice?(request: RegisterDeviceRequest): Promise; unregisterDevice?(request: UnregisterDeviceRequest): Promise; getNotificationPreferences?(request: GetNotificationPreferencesRequest): Promise; @@ -1454,18 +1484,24 @@ export interface ObjectStackProtocol { listNotifications?(request: ListNotificationsRequest): Promise; markNotificationsRead?(request: MarkNotificationsReadRequest): Promise; markAllNotificationsRead?(request: MarkAllNotificationsReadRequest): Promise; +} - // AI (optional — chat is now handled by Vercel AI SDK wire protocol) +/** AI (optional — chat is now handled by the Vercel AI SDK wire protocol). */ +export interface AiProtocol { aiNlq?(request: AiNlqRequest): Promise; aiSuggest?(request: AiSuggestRequest): Promise; aiInsights?(request: AiInsightsRequest): Promise; +} - // i18n (optional) +/** Localization (optional). */ +export interface I18nProtocol { getLocales?(request: GetLocalesRequest): Promise; getTranslations?(request: GetTranslationsRequest): Promise; getFieldLabels?(request: GetFieldLabelsRequest): Promise; +} - // Feed (optional) +/** Feed / social (optional). */ +export interface FeedProtocol { listFeed?(request: GetFeedRequest): Promise; createFeedItem?(request: CreateFeedItemRequest): Promise; updateFeedItem?(request: UpdateFeedItemRequest): Promise; @@ -1481,3 +1517,26 @@ export interface ObjectStackProtocol { feedSubscribe?(request: SubscribeRequest): Promise; feedUnsubscribe?(request: FeedUnsubscribeRequest): Promise; } + +/** + * ObjectStackProtocol — composition of the per-domain contracts above + * (ADR-0076 D9). Shape-identical to the historical flat interface, so every + * existing implementation/consumer is unaffected. Prefer depending on the + * narrowest slice (e.g. `DataProtocol`). Per ADR-0076 D9 (rev.7) this union is + * transitional; the end-state dissolves it (capability availability comes from + * the discovery `services` registry, not a static union). + */ +export interface ObjectStackProtocol extends + DataProtocol, + MetadataProtocol, + AnalyticsProtocol, + AutomationProtocol, + PackageProtocol, + ViewProtocol, + PermissionProtocol, + WorkflowProtocol, + RealtimeProtocol, + NotificationProtocol, + AiProtocol, + I18nProtocol, + FeedProtocol {}