feat(spec): segment ObjectStackProtocol into per-domain interfaces (ADR-0076 D9, step 1) (#2429)

* feat(spec): segment ObjectStackProtocol into per-domain protocol interfaces (ADR-0076 D9)

Split the 70-method, 11-domain ObjectStackProtocol god-interface into focused,
exported per-domain contracts (DataProtocol, MetadataProtocol, AnalyticsProtocol,
AutomationProtocol, PackageProtocol, ViewProtocol, PermissionProtocol,
WorkflowProtocol, RealtimeProtocol, NotificationProtocol, AiProtocol,
I18nProtocol, FeedProtocol). ObjectStackProtocol now `extends` all of them —
shape-identical to the old flat interface, so non-breaking.

This is the lowest-risk, foundational step of ADR-0076 D9: pure type-level,
shape-preserving, no runtime change. Consumers can now depend on the narrowest
slice (e.g. DataProtocol). The composed union is transitional (D9 rev.7).

Verified: turbo build (spec + rest + metadata-protocol + objectql) green incl.
DTS — the impl class still satisfies `implements ObjectStackProtocol`; spec
suite 243 files / 6602 tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(spec): update api-surface snapshot for the 13 segmented protocol interfaces

The api-surface ratchet flagged 13 additive exports (0 breaking) from the
ObjectStackProtocol segmentation. Regenerated the committed snapshot.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.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.

packages/spec/api-surface.json

@@ -2050,13 +2050,15 @@
     "AiNlqRequestSchema (const)",
     "AiNlqResponse (type)",
     "AiNlqResponseSchema (const)",
+    "AiProtocol (interface)",
     "AiSuggestRequest (type)",
     "AiSuggestRequestSchema (const)",
     "AiSuggestResponse (type)",
     "AiSuggestResponseSchema (const)",
     "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)",

packages/spec/src/api/protocol.zod.ts

@@ -1376,7 +1376,34 @@ export type ObjectStackProtocolZod = z.infer<typeof ObjectStackProtocolSchema>;
  * 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<FindDataResponse>;
+  getData(request: GetDataRequest): Promise<GetDataResponse>;
+  createData(request: CreateDataRequest): Promise<CreateDataResponse>;
+  updateData(request: UpdateDataRequest): Promise<UpdateDataResponse>;
+  deleteData(request: DeleteDataRequest): Promise<DeleteDataResponse>;
+
+  // Batch Operations (optional)
+  batchData?(request: BatchDataRequest): Promise<BatchDataResponse>;
+  createManyData?(request: CreateManyDataRequest): Promise<CreateManyDataResponse>;
+  updateManyData?(request: UpdateManyDataRequest): Promise<UpdateManyDataResponse>;
+  deleteManyData?(request: DeleteManyDataRequest): Promise<DeleteManyDataResponse>;
+}
+
+/** Discovery + metadata (sys_metadata) management. */
+export interface MetadataProtocol {
   // Discovery & Metadata (core)
   getDiscovery(request?: GetDiscoveryRequest): Promise<GetDiscoveryResponse>;
   getMetaTypes(request?: GetMetaTypesRequest): Promise<GetMetaTypesResponse>;
@@ -1392,80 +1419,89 @@ export interface ObjectStackProtocol {
   deleteMetaItem?(request: DeleteMetaItemRequest): Promise<DeleteMetaItemResponse>;
   getMetaItemCached?(request: GetMetaItemCachedRequest): Promise<GetMetaItemCachedResponse>;
   getUiView?(request: GetUiViewRequest): Promise<GetUiViewResponse>;
-  
-  // Analytics (optional)
+}
+
+/** Analytics (optional). */
+export interface AnalyticsProtocol {
   analyticsQuery?(request: AnalyticsQueryRequest): Promise<AnalyticsResultResponse>;
   getAnalyticsMeta?(request: GetAnalyticsMetaRequest): Promise<GetAnalyticsMetaResponse>;
+}
 
-  // Automation (optional)
+/** Automation (optional). */
+export interface AutomationProtocol {
   triggerAutomation?(request: AutomationTriggerRequest): Promise<AutomationTriggerResponse>;
+}
 
-  // Package Management (optional)
+/** Package lifecycle (optional). */
+export interface PackageProtocol {
   listPackages?(request: ListPackagesRequest): Promise<ListPackagesResponse>;
   getPackage?(request: GetPackageRequest): Promise<GetPackageResponse>;
   installPackage?(request: InstallPackageRequest): Promise<InstallPackageResponse>;
   uninstallPackage?(request: UninstallPackageRequest): Promise<UninstallPackageResponse>;
   enablePackage?(request: EnablePackageRequest): Promise<EnablePackageResponse>;
   disablePackage?(request: DisablePackageRequest): Promise<DisablePackageResponse>;
+}
 
-  // Data Operations (core)
-  findData(request: FindDataRequest): Promise<FindDataResponse>;
-  getData(request: GetDataRequest): Promise<GetDataResponse>;
-  createData(request: CreateDataRequest): Promise<CreateDataResponse>;
-  updateData(request: UpdateDataRequest): Promise<UpdateDataResponse>;
-  deleteData(request: DeleteDataRequest): Promise<DeleteDataResponse>;
-  
-  // Batch Operations (optional)
-  batchData?(request: BatchDataRequest): Promise<BatchDataResponse>;
-  createManyData?(request: CreateManyDataRequest): Promise<CreateManyDataResponse>;
-  updateManyData?(request: UpdateManyDataRequest): Promise<UpdateManyDataResponse>;
-  deleteManyData?(request: DeleteManyDataRequest): Promise<DeleteManyDataResponse>;
-
-  // View Management (optional)
+/** View management (optional). */
+export interface ViewProtocol {
   listViews?(request: ListViewsRequest): Promise<ListViewsResponse>;
   getView?(request: GetViewRequest): Promise<GetViewResponse>;
   createView?(request: CreateViewRequest): Promise<CreateViewResponse>;
   updateView?(request: UpdateViewRequest): Promise<UpdateViewResponse>;
   deleteView?(request: DeleteViewRequest): Promise<DeleteViewResponse>;
+}
 
-  // Permissions (optional)
+/** Permissions (optional). */
+export interface PermissionProtocol {
   checkPermission?(request: CheckPermissionRequest): Promise<CheckPermissionResponse>;
   getObjectPermissions?(request: GetObjectPermissionsRequest): Promise<GetObjectPermissionsResponse>;
   getEffectivePermissions?(request: GetEffectivePermissionsRequest): Promise<GetEffectivePermissionsResponse>;
+}
 
-  // Workflows (optional)
+/** Workflows (optional). */
+export interface WorkflowProtocol {
   getWorkflowConfig?(request: GetWorkflowConfigRequest): Promise<GetWorkflowConfigResponse>;
   getWorkflowState?(request: GetWorkflowStateRequest): Promise<GetWorkflowStateResponse>;
   workflowTransition?(request: WorkflowTransitionRequest): Promise<WorkflowTransitionResponse>;
+}
 
-  // Realtime (optional)
+/** Realtime / presence (optional). */
+export interface RealtimeProtocol {
   realtimeConnect?(request: RealtimeConnectRequest): Promise<RealtimeConnectResponse>;
   realtimeDisconnect?(request: RealtimeDisconnectRequest): Promise<RealtimeDisconnectResponse>;
   realtimeSubscribe?(request: RealtimeSubscribeRequest): Promise<RealtimeSubscribeResponse>;
   realtimeUnsubscribe?(request: RealtimeUnsubscribeRequest): Promise<RealtimeUnsubscribeResponse>;
   setPresence?(request: SetPresenceRequest): Promise<SetPresenceResponse>;
   getPresence?(request: GetPresenceRequest): Promise<GetPresenceResponse>;
+}
 
-  // Notifications (optional)
+/** Notifications (optional). */
+export interface NotificationProtocol {
   registerDevice?(request: RegisterDeviceRequest): Promise<RegisterDeviceResponse>;
   unregisterDevice?(request: UnregisterDeviceRequest): Promise<UnregisterDeviceResponse>;
   getNotificationPreferences?(request: GetNotificationPreferencesRequest): Promise<GetNotificationPreferencesResponse>;
   updateNotificationPreferences?(request: UpdateNotificationPreferencesRequest): Promise<UpdateNotificationPreferencesResponse>;
   listNotifications?(request: ListNotificationsRequest): Promise<ListNotificationsResponse>;
   markNotificationsRead?(request: MarkNotificationsReadRequest): Promise<MarkNotificationsReadResponse>;
   markAllNotificationsRead?(request: MarkAllNotificationsReadRequest): Promise<MarkAllNotificationsReadResponse>;
+}
 
-  // 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<AiNlqResponse>;
   aiSuggest?(request: AiSuggestRequest): Promise<AiSuggestResponse>;
   aiInsights?(request: AiInsightsRequest): Promise<AiInsightsResponse>;
+}
 
-  // i18n (optional)
+/** Localization (optional). */
+export interface I18nProtocol {
   getLocales?(request: GetLocalesRequest): Promise<GetLocalesResponse>;
   getTranslations?(request: GetTranslationsRequest): Promise<GetTranslationsResponse>;
   getFieldLabels?(request: GetFieldLabelsRequest): Promise<GetFieldLabelsResponse>;
+}
 
-  // Feed (optional)
+/** Feed / social (optional). */
+export interface FeedProtocol {
   listFeed?(request: GetFeedRequest): Promise<GetFeedResponse>;
   createFeedItem?(request: CreateFeedItemRequest): Promise<CreateFeedItemResponse>;
   updateFeedItem?(request: UpdateFeedItemRequest): Promise<UpdateFeedItemResponse>;
@@ -1481,3 +1517,26 @@ export interface ObjectStackProtocol {
   feedSubscribe?(request: SubscribeRequest): Promise<SubscribeResponse>;
   feedUnsubscribe?(request: FeedUnsubscribeRequest): Promise<UnsubscribeResponse>;
 }
+
+/**
+ * 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 {}