@wovin/core 0.1.36 → 0.2.2

package/src/query/situations.ts

@@ -0,0 +1,261 @@
+import { Applog } from '../applog/datom-types.ts'
+import { query } from './basic.ts'
+import { QueryNode } from './types.ts'
+import { Logger } from 'besonders-logger'
+
+const { WARN, LOG, DEBUG, VERBOSE, ERROR } = Logger.setup(Logger.INFO) // eslint-disable-line no-unused-vars
+
+/**
+ * Situations are meant to flag and possibly autocorrect or autosuggest solutions
+ *
+ * Types of Situations:
+ * Divergences = leaf nodes that are based on different previous versions/contexts
+ * Conflicts/Disagreement = different agents setting the same attribute (based on same previous)
+ * Overwrite = one agent's action implicitly overrides another's without explicit confirmation
+ * Conscious Disagreement = agents explicitly acknowledge and accept conflicting changes
+ * Suggestions = recommendations for improvements or alternatives
+ */
+interface Situation {
+	name: string
+	desc: string
+	intensity: number
+	type: typeof SituationTypes[keyof typeof SituationTypes]
+	query: typeof query // wovin can export common examples
+	resolutionOptions: Resolution[]
+	metadata?: {
+		agentId?: string
+		timestamp?: number
+		context?: Record<string, any>
+	}
+}
+
+interface QueryResultWithSituations {
+	result: any
+	situations: Situation[]
+	threadView?: ThreadView
+}
+
+interface ThreadView {
+	id: string
+	situations: SituatedMessage[]
+	resolutionState: ResolutionState
+}
+
+interface SituatedMessage {
+	id: string
+	situation: Situation
+	message: string
+	resolutions: ResolutionAction[]
+	timestamp: number
+	agentId?: string
+}
+
+interface ResolutionState {
+	pending: string[] // situation IDs
+	resolved: string[] // situation IDs
+	ignored: string[] // situation IDs
+}
+
+interface ResolutionAction {
+	name: string
+	applied: boolean
+	appliedAt?: number
+	appliedBy?: string
+}
+
+const SituationTypes = {
+	divergence: 'divergence',
+	disagreement: 'disagreement',
+	overwrite: 'overwrite',
+	consciousDisagreement: 'consciousDisagreement',
+	suggestion: 'suggestion',
+} as const
+interface Resolution {
+	name: string
+	desc: string
+	assertion: () => Applog[]
+}
+const ContentDivergence = {
+	name: 'ContentDivergence',
+	desc: 'block/content changes from different agents based on different pv logs',
+	intensity: 10,
+	type: SituationTypes.divergence,
+	query: QueryNode,
+	resolutionOptions: [],
+}
+
+const AttributeOverwrite = {
+	name: 'AttributeOverwrite',
+	desc: 'one agent implicitly overwrites another agent\'s attribute change without confirmation',
+	intensity: 8,
+	type: SituationTypes.overwrite,
+	query: QueryNode,
+	resolutionOptions: [
+		{
+			name: 'restore',
+			desc: 'restore the previous value',
+			assertion: () => [] // TODO: implement restoration logic
+		},
+		{
+			name: 'confirm',
+			desc: 'confirm the overwrite as intentional',
+			assertion: () => [] // TODO: implement confirmation logic
+		}
+	],
+}
+
+const ConsciousDisagreement = {
+	name: 'ConsciousDisagreement',
+	desc: 'agents explicitly acknowledge and accept conflicting changes to the same attribute',
+	intensity: 5,
+	type: SituationTypes.consciousDisagreement,
+	query: QueryNode,
+	resolutionOptions: [
+		{
+			name: 'merge',
+			desc: 'create a merged version that incorporates both perspectives',
+			assertion: () => [] // TODO: implement merge logic
+		},
+		{
+			name: 'branch',
+			desc: 'create separate branches for each perspective',
+			assertion: () => [] // TODO: implement branching logic
+		}
+	],
+}
+
+const ContentSuggestion = {
+	name: 'ContentSuggestion',
+	desc: 'AI or agent suggests improvements to existing content',
+	intensity: 3,
+	type: SituationTypes.suggestion,
+	query: QueryNode,
+	resolutionOptions: [
+		{
+			name: 'accept',
+			desc: 'accept the suggestion and apply changes',
+			assertion: () => [] // TODO: implement acceptance logic
+		},
+		{
+			name: 'reject',
+			desc: 'reject the suggestion',
+			assertion: () => [] // TODO: implement rejection logic
+		},
+		{
+			name: 'modify',
+			desc: 'accept with modifications',
+			assertion: () => [] // TODO: implement modification logic
+		}
+	],
+}
+
+/**
+ * Creates a thread view for situations detected in query results
+ */
+export function createThreadForSituations(
+	result: any,
+	situations: Situation[],
+	options: {
+		threadId?: string
+		groupByType?: boolean
+		sortByIntensity?: boolean
+	} = {}
+): QueryResultWithSituations {
+	const threadId = options.threadId || `thread_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+	
+	// Sort situations if requested
+	let sortedSituations = [...situations]
+	if (options.sortByIntensity) {
+		sortedSituations.sort((a, b) => b.intensity - a.intensity)
+	}
+
+	// Group by type if requested
+	const threadMessages: SituatedMessage[] = sortedSituations.map((situation, index) => ({
+		id: `${threadId}_msg_${index}`,
+		situation,
+		message: formatSituationMessage(situation),
+		resolutions: situation.resolutionOptions.map(option => ({
+			name: option.name,
+			applied: false,
+		})),
+		timestamp: Date.now(),
+		agentId: situation.metadata?.agentId,
+	}))
+
+	const threadView: ThreadView = {
+		id: threadId,
+		situations: threadMessages,
+		resolutionState: {
+			pending: threadMessages.map(msg => msg.id),
+			resolved: [],
+			ignored: [],
+		},
+	}
+
+	return {
+		result,
+		situations,
+		threadView,
+	}
+}
+
+/**
+ * Formats a situation into a human-readable message for the thread
+ */
+function formatSituationMessage(situation: Situation): string {
+	const typeEmoji = {
+		[SituationTypes.divergence]: '🔀',
+		[SituationTypes.disagreement]: '⚠️',
+		[SituationTypes.overwrite]: '🔄',
+		[SituationTypes.consciousDisagreement]: '💭',
+		[SituationTypes.suggestion]: '💡',
+	}
+
+	const emoji = typeEmoji[situation.type] || '❓'
+	return `${emoji} **${situation.name}**: ${situation.desc} (intensity: ${situation.intensity})`
+}
+
+/**
+ * Applies a resolution action to a situation in a thread
+ */
+export function applyResolution(
+	threadView: ThreadView,
+	messageId: string,
+	resolutionName: string,
+	appliedBy: string
+): ThreadView {
+	const updatedMessages = threadView.situations.map(msg => {
+		if (msg.id === messageId) {
+			const updatedResolutions = msg.resolutions.map(res => 
+				res.name === resolutionName 
+					? { ...res, applied: true, appliedAt: Date.now(), appliedBy }
+					: res
+			)
+			
+			return {
+				...msg,
+				resolutions: updatedResolutions,
+			}
+		}
+		return msg
+	})
+
+	const message = updatedMessages.find(msg => msg.id === messageId)
+	const hasAppliedResolution = message?.resolutions.some(res => res.applied)
+
+	const resolutionState = {
+		...threadView.resolutionState,
+		pending: hasAppliedResolution 
+			? threadView.resolutionState.pending.filter(id => id !== messageId)
+			: threadView.resolutionState.pending,
+		resolved: hasAppliedResolution 
+			? [...threadView.resolutionState.resolved, messageId]
+			: threadView.resolutionState.resolved,
+	}
+
+	return {
+		...threadView,
+		situations: updatedMessages,
+		resolutionState,
+	}
+}

package/src/query/subscribable.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, it, vi } from 'vitest'
+import { ArrayEvent, isArrayInitEvent, SubscribableArrayImpl, SubscribableImpl } from './subscribable.ts'
+
+describe('SubscribableImpl', () => {
+	it('provides value synchronously', () => {
+		const s = new SubscribableImpl(42)
+		expect(s.value).toBe(42)
+	})
+
+	it('does NOT fire callback on subscribe', () => {
+		const s = new SubscribableImpl('hello')
+		const calls: string[] = []
+		s.subscribe(() => calls.push(s.value))
+		expect(calls).toEqual([])
+	})
+
+	it('notifies on _set', () => {
+		const s = new SubscribableImpl(1)
+		const values: number[] = []
+		s.subscribe(() => values.push(s.value))
+		s._set(2)
+		s._set(3)
+		expect(values).toEqual([2, 3])
+		expect(s.value).toBe(3)
+	})
+
+	it('activates upstream lazily on first subscribe', () => {
+		const deactivate = vi.fn()
+		const activate = vi.fn(() => deactivate)
+		const s = new SubscribableImpl(0, activate)
+
+		expect(activate).not.toHaveBeenCalled()
+		const unsub = s.subscribe(() => {})
+		expect(activate).toHaveBeenCalledOnce()
+
+		// Second subscriber doesn't re-activate
+		const unsub2 = s.subscribe(() => {})
+		expect(activate).toHaveBeenCalledOnce()
+
+		// Unsubscribe one — upstream stays active
+		unsub2()
+		expect(deactivate).not.toHaveBeenCalled()
+
+		// Unsubscribe last — upstream deactivates
+		unsub()
+		expect(deactivate).toHaveBeenCalledOnce()
+	})
+
+	it('re-activates upstream after full unsubscribe + re-subscribe', () => {
+		const deactivate = vi.fn()
+		const activate = vi.fn(() => deactivate)
+		const s = new SubscribableImpl(0, activate)
+
+		const unsub1 = s.subscribe(() => {})
+		unsub1()
+		expect(activate).toHaveBeenCalledTimes(1)
+		expect(deactivate).toHaveBeenCalledTimes(1)
+
+		const unsub2 = s.subscribe(() => {})
+		expect(activate).toHaveBeenCalledTimes(2)
+		unsub2()
+		expect(deactivate).toHaveBeenCalledTimes(2)
+	})
+
+	it('snapshots subscribers to handle unsubscribe during notification', () => {
+		const s = new SubscribableImpl(0)
+		const events: string[] = []
+		let unsub2: (() => void) | null = null
+
+		s.subscribe(() => {
+			events.push('sub1')
+			unsub2?.()
+		})
+		unsub2 = s.subscribe(() => {
+			events.push('sub2')
+		})
+
+		// No immediate callbacks — nothing fired yet
+		expect(events).toEqual([])
+
+		// _set — sub1 runs and unsubscribes sub2, but sub2 still fires (snapshot)
+		s._set(1)
+		expect(events).toEqual(['sub1', 'sub2'])
+	})
+
+	it('dispose tears down upstream and clears subscribers', () => {
+		const deactivate = vi.fn()
+		const activate = vi.fn(() => deactivate)
+		const s = new SubscribableImpl(0, activate)
+
+		s.subscribe(() => {})
+		expect(activate).toHaveBeenCalledOnce()
+
+		s.dispose()
+		expect(deactivate).toHaveBeenCalledOnce()
+
+		// _set after dispose — no error, no subscribers
+		s._set(99)
+		expect(s.value).toBe(99)
+	})
+
+	it('works with complex types', () => {
+		const s = new SubscribableImpl<{ name: string } | null>(null)
+		const values: ({ name: string } | null)[] = []
+		s.subscribe(() => values.push(s.value))
+		s._set({ name: 'Alice' })
+		s._set(null)
+		expect(values).toEqual([{ name: 'Alice' }, null])
+	})
+})
+
+describe('SubscribableArrayImpl', () => {
+	it('provides items synchronously', () => {
+		const arr = new SubscribableArrayImpl([1, 2, 3])
+		expect(arr.items).toEqual([1, 2, 3])
+		expect(arr.length).toBe(3)
+	})
+
+	it('does NOT send init event on subscribe', () => {
+		const arr = new SubscribableArrayImpl([1, 2, 3])
+		const events: ArrayEvent<number>[] = []
+		arr.subscribe(e => events.push(e))
+		expect(events).toEqual([])
+		// Current state is available via .items
+		expect(arr.items).toEqual([1, 2, 3])
+	})
+
+	it('notifies on _push', () => {
+		const arr = new SubscribableArrayImpl([1])
+		const events: ArrayEvent<number>[] = []
+		arr.subscribe(e => events.push(e))
+		arr._push(2, 3)
+		expect(arr.items).toEqual([1, 2, 3])
+		expect(events).toEqual([
+			{ added: [2, 3], removed: null },
+		])
+	})
+
+	it('notifies on _remove', () => {
+		const arr = new SubscribableArrayImpl([1, 2, 3])
+		const events: ArrayEvent<number>[] = []
+		arr.subscribe(e => events.push(e))
+		arr._remove([2])
+		expect(arr.items).toEqual([1, 3])
+		expect(events).toEqual([
+			{ added: [], removed: [2] },
+		])
+	})
+
+	it('notifies on _reset', () => {
+		const arr = new SubscribableArrayImpl([1, 2])
+		const events: ArrayEvent<number>[] = []
+		arr.subscribe(e => events.push(e))
+		arr._reset([10, 20])
+		expect(arr.items).toEqual([10, 20])
+		expect(events).toEqual([
+			{ init: [10, 20] },
+		])
+	})
+
+	it('activates upstream lazily on first subscribe', () => {
+		const deactivate = vi.fn()
+		const activate = vi.fn(() => deactivate)
+		const arr = new SubscribableArrayImpl([1], activate)
+
+		expect(activate).not.toHaveBeenCalled()
+		const unsub = arr.subscribe(() => {})
+		expect(activate).toHaveBeenCalledOnce()
+
+		// Second subscriber doesn't re-activate
+		const unsub2 = arr.subscribe(() => {})
+		expect(activate).toHaveBeenCalledOnce()
+
+		// Unsubscribe one — upstream stays active
+		unsub2()
+		expect(deactivate).not.toHaveBeenCalled()
+
+		// Unsubscribe last — upstream deactivates
+		unsub()
+		expect(deactivate).toHaveBeenCalledOnce()
+	})
+
+	it('re-activates upstream after full unsubscribe + re-subscribe', () => {
+		const deactivate = vi.fn()
+		const activate = vi.fn(() => deactivate)
+		const arr = new SubscribableArrayImpl([1], activate)
+
+		const unsub1 = arr.subscribe(() => {})
+		unsub1()
+		expect(activate).toHaveBeenCalledTimes(1)
+		expect(deactivate).toHaveBeenCalledTimes(1)
+
+		// Re-subscribe should re-activate
+		const unsub2 = arr.subscribe(() => {})
+		expect(activate).toHaveBeenCalledTimes(2)
+		unsub2()
+		expect(deactivate).toHaveBeenCalledTimes(2)
+	})
+
+	it('snapshots subscribers to handle unsubscribe during notification', () => {
+		const arr = new SubscribableArrayImpl<number>([])
+		const events: string[] = []
+		let unsub2: (() => void) | null = null
+
+		arr.subscribe(() => {
+			events.push('sub1')
+			// Unsubscribe sub2 during notification
+			unsub2?.()
+		})
+		unsub2 = arr.subscribe(() => {
+			events.push('sub2')
+		})
+
+		// No init events — nothing fired yet
+		expect(events).toEqual([])
+
+		// Push — sub1 runs and unsubscribes sub2, but sub2 should still receive this event
+		// (because we snapshot subscribers before iterating)
+		arr._push(1)
+		expect(events).toEqual(['sub1', 'sub2'])
+	})
+
+	it('dispose tears down upstream and clears subscribers', () => {
+		const deactivate = vi.fn()
+		const activate = vi.fn(() => deactivate)
+		const arr = new SubscribableArrayImpl([1], activate)
+
+		arr.subscribe(() => {})
+		expect(activate).toHaveBeenCalledOnce()
+
+		arr.dispose()
+		expect(deactivate).toHaveBeenCalledOnce()
+
+		// Push after dispose — no subscribers to notify (no error)
+		arr._push(2)
+		expect(arr.items).toEqual([1, 2])
+	})
+})
+
+describe('isArrayInitEvent', () => {
+	it('identifies init events', () => {
+		expect(isArrayInitEvent({ init: [1, 2] })).toBe(true)
+		expect(isArrayInitEvent({ added: [1], removed: null })).toBe(false)
+	})
+})