Overview

This document specifies the Subscriptions gRPC service that lets clients subscribe and unsubscribe to document paths within an account, and list active subscriptions. Subscriptions can be recursive (covering an entire directory) and may be created asynchronously to avoid blocking on initial sync.

Goals

Provide a minimal API to subscribe/unsubscribe to resources identified by (account, path).

Support recursive subscriptions to monitor entire directories.

Offer pagination for listing active subscriptions.

Allow async fire‑and‑forget creation to decouple UI from initial sync.

Non‑Goals

Delivering the event stream itself (handled by Activity/Feed or Sync layers).

Authorization policy definition (capability checks are enforced elsewhere).

Batch subscribe/unsubscribe (can be added later).

Protocol Definition

syntax = "proto3";

package com.seed.activity.v1alpha;

import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";

option go_package = "seed/backend/genproto/activity/v1alpha;activity";

// Subscriptions service provides subscription capabilities.
service Subscriptions {
  // Subscribe to a document or space.
  rpc Subscribe(SubscribeRequest) returns (google.protobuf.Empty);

  // Remove a subscription.
  rpc Unsubscribe(UnsubscribeRequest) returns (google.protobuf.Empty);

  // Lists active subscriptions.
  rpc ListSubscriptions(ListSubscriptionsRequest) returns (ListSubscriptionsResponse);
}

// Subscribe to a resource
message SubscribeRequest {
  // Required. The ID of the account where the subscribed document is located.
  string account = 1;

  // Required. Path of