Implement collection dependency change notifications

[jamlung-ri]

Priority: 2
Quarter: Q2 2026
Bucket: CIEL Implementer

Overview

Surface dependency staleness to collection owners when a source dependency (e.g., CIEL) has released a newer version than what their collection is currently resolved to, enabling them to review the impact and update their collection.

Spec

ocl-kb/tbv3/02_capabilities/manage-versions-and-expansions.md § Dependency Notifications, and ocl-kb/tbv3/03_workflows/update-collection-source-version.md (Step 1: Review the Staleness Banner).

User Story

As a collection owner, I want to see when my source dependencies have newer versions available so that I can review the impact, test updates, and keep my collection current.

Implementation Approach

This ticket is scoped to Part 1 of a two-part plan (per 2026-06-16 squad discussion). Part 1 is an on-demand API function for version synchrony — given a collection, compute which of its resolved source dependencies have a newer released version available and what changed. Surface this result in Term Browser when the collection is visited: collection header banner + "Needs Refresh" expansion badge. No dependency on the events framework.

Part 2 (proactive notification/alerting system) is deferred — see Out of Scope below.

M44 Scope — Version Synchrony API + In-Context Surfacing

Detection API

• API function: given a collection, return which of its resolved source dependencies have a newer released version available, along with a change summary (concepts added/retired/modified, affected reference count)
• Function runs on-demand (called when a user visits a collection); does not require a maintained dependency graph or persistent event records
• Returns no staleness signal when the collection is already at the latest version of all dependencies, or when a newer version exists but has no changes affecting the collection's references

UI Surfaces

• Collection header banner: persistent warning when the collection has at least one dependency with a newer version available, dismissible per session ("Snooze"), reappears on next visit until addressed
• "Needs Refresh" badge on expansions whose resolved source versions are behind the latest available releases

Content

• Source chip (name + org), new version ID + release date
• Change summary: "[N] added, [N] retired, [N] modified concepts affect your collection"
• "Review updates →" CTA into the Update Collection workflow (Implement collection dependency update workflow #2349)

Out of Scope for M44

Moved to ocl-kb/tbv3/tbv3-deferred-features.md § Dependency Notifications:

• Per-dependency notification preferences (channel/frequency configuration)
• Notification history / export
• Downstream notification to dependent collection owners (reverse-dependency graph)
• Proactive in-app notification bell + Notification Center (Part 2)
• External notification channels (email, push, Slack/WhatsApp) + events framework integration (Part 2)

Webhook/API notification channel is tracked separately and remains in this milestone — see #2535.

Related Issues

• Implement collection dependency update workflow #2349 - Accept/Reject Dependency Update (review-and-accept workflow)
• Implement webhook in OCL for external sync and workflow automation #2535 - Webhook for external sync and workflow automation