Activity System

Activity as OS-native Context Timeline Layer

@prox-os/activity is the shared foreground activity timeline layer for Prox OS. It normalizes cross-domain product history into serializable activity events and composable React primitives.

Activity is meant for OS context: what happened in an app, workspace, resource, file, AI run, notification, collaboration thread, security review, command, or developer tool.

What Activity Is Not

Activity is not an analytics SDK, telemetry system, event store, message queue, realtime subscription layer, security audit backend, or notification center. Phase 1 is mock-first and runtime-agnostic.

Runtime-agnostic Event Boundary

Domain packages produce domain events or view models. Activity adapters convert those objects into OsActivityEvent objects:

domain event -> activity event -> feed/timeline/digest -> action intent

Runtime execution, persistence, delivery, and backend fan-out stay outside this package.

Event Flow

1. A domain package emits or exposes a domain object.
2. An activity adapter maps it into OsActivityEvent.
3. Helpers filter, sort, group, summarize, redact, or digest the events.
4. UI primitives render feed, timeline, detail, stats, and related resources.
5. User actions are emitted as action refs or callbacks for the runtime.

Related Resource Flow

An activity event can link to files, folders, threads, reviews, AI artifacts, security reviews, notifications, search results, workspace resources, projects, apps, routes, and external URLs. Activity displays these relationships but does not open or mutate them directly.

Redaction and Privacy Flow

Activity includes visibility, sensitivity, and redacted fields so a future runtime can hide restricted details while preserving useful timeline context. Phase 1 only renders mock redaction and does not enforce permissions.

Relationship with Other Packages

• Actions: Activity records action requests/results and can expose action refs.
• Command: Command Palette can open feeds or jump to activity details.
• Notifications: notifications can map into activity, but delivery and attention policy stay in @prox-os/notifications.
• Security UI: security and audit events can map into activity summaries, but real audit trust and compliance stay in security/backend systems.
• Collaboration: comments, mentions, threads, reviews, and sharing can map into activity, while collaboration objects remain owned by @prox-os/collaboration.
• Files: file events can map into activity, while browser, picker, preview, and transfer UI remain owned by @prox-os/files.
• Search: search events can map into activity, and future activity events can be indexed by search.
• AI UI: AI sessions, runs, tool calls, approvals, artifacts, and context usage can map into activity, while AI runtime stays elsewhere.
• Workspace UI: workspace dashboards can embed activity feeds, while workspace membership and resources remain owned by @prox-os/workspace-ui.

Why Phase 1 Avoids Backends

The package is a UI and contract layer. Binding it to analytics, event store, realtime, audit, or telemetry infrastructure would make a reusable primitive package own runtime concerns too early.

Phase 1 intentionally avoids:

• PostHog, Segment, Amplitude, Plausible, Mixpanel.
• Sentry, Datadog, Logflare, or logging vendor SDKs.
• WebSocket, SSE, Firebase, Supabase Realtime, Liveblocks, or socket clients.
• Queue, stream, event sourcing, or audit persistence SDKs.

Future Provider Adapters

• Local activity provider.
• Backend event store API.
• Workspace-scoped activity provider.
• Notification bridge.
• Search indexing bridge.
• Security/audit bridge.
• Analytics export bridge.
• Realtime activity stream adapter.

Data Model Sketch

OsActivityActor
  -> OsActivityEvent.actor

OsActivityTarget
  -> OsActivityEvent.target

OsActivityObject
  -> OsActivityEvent.object

OsActivityEvent
  -> OsActivityFeed.events
  -> OsActivityGroup.events
  -> OsActivityDigest.events/highlights
  -> OsActivityStats

Privacy, Retention, Workspace, and Creator-space Considerations

Activity can contain sensitive context from files, AI sessions, workspace resources, security events, and collaboration threads. Future runtime providers should apply workspace policies, viewer permissions, retention rules, creator space public/private boundaries, and redaction before events reach UI.

The package only models those states; it does not enforce them.