@wovin/core 0.1.36 → 0.2.0

package/src/thread/joinThreads.test.ts

@@ -0,0 +1,304 @@
+/**
+ * Tests for joinThreads — the multi-parent thread merge.
+ *
+ * Covers: initial merge, incremental adds, deduplication, setParents,
+ * triggerRemap, and subscriber notifications.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { finalizeApplogForInsert, joinThreads } from '../applog/applog-helpers.ts'
+import { sortApplogsByTs } from '../applog/applog-utils.ts'
+import type { Applog, ApplogForInsert, CidString } from '../applog/datom-types.ts'
+import { isInitEvent, type ThreadEvent } from './basic.ts'
+import { ThreadInMemory } from './writeable.ts'
+
+// ─── Helpers ────────────────────────────────────────────────────
+
+let tsCounter = 0
+
+/** Create a valid Applog with proper CID (can be used with insertRaw) */
+function makeLog(overrides: Partial<Applog> & Pick<ApplogForInsert, 'en' | 'at' | 'vl'>): Applog {
+	tsCounter++
+	const base = {
+		ts: overrides.ts ?? new Date(1700000000000 + tsCounter * 1000).toISOString(),
+		pv: null,
+		ag: 'testAgent',
+		...overrides,
+	}
+	// Use finalizeApplogForInsert to get a real CID
+	return finalizeApplogForInsert(base as ApplogForInsert, {})
+}
+
+function makeLogs(...specs: Array<Partial<Applog> & Pick<ApplogForInsert, 'en' | 'at' | 'vl'>>): Applog[] {
+	return sortApplogsByTs(specs.map(s => makeLog(s)))
+}
+
+function threadFrom(logs: Applog[], name = 'test'): ThreadInMemory {
+	return ThreadInMemory.fromArray(logs, name)
+}
+
+afterEach(() => {
+	tsCounter = 0
+})
+
+// ═════════════════════════════════════════════════════════════════
+// Initial merge (compute)
+// ═════════════════════════════════════════════════════════════════
+
+describe('joinThreads — initial merge', () => {
+	it('merges applogs from two threads', () => {
+		const logsA = makeLogs(
+			{ en: 'e1', at: 'name', vl: 'Alice' },
+		)
+		const logsB = makeLogs(
+			{ en: 'e2', at: 'name', vl: 'Bob' },
+		)
+		const joined = joinThreads([threadFrom(logsA, 'A'), threadFrom(logsB, 'B')])
+
+		expect(joined.size).toBe(2)
+		expect(joined.applogs.map(l => l.vl)).toContain('Alice')
+		expect(joined.applogs.map(l => l.vl)).toContain('Bob')
+	})
+
+	it('deduplicates identical applogs across threads', () => {
+		const shared = makeLog({ en: 'e1', at: 'name', vl: 'Alice' })
+		const a = threadFrom([shared], 'A')
+		const b = threadFrom([shared], 'B')
+		const joined = joinThreads([a, b])
+
+		expect(joined.size).toBe(1)
+	})
+
+	it('sorts merged result by timestamp', () => {
+		const early = makeLog({ en: 'e1', at: 'x', vl: 1, ts: '2020-01-01T00:00:00Z' })
+		const late = makeLog({ en: 'e2', at: 'x', vl: 2, ts: '2025-01-01T00:00:00Z' })
+		// Give them to threads in reverse order
+		const joined = joinThreads([threadFrom([late], 'A'), threadFrom([early], 'B')])
+
+		expect(joined.applogs[0]).toBe(early)
+		expect(joined.applogs[1]).toBe(late)
+	})
+
+	it('handles empty threads', () => {
+		const logsA = makeLogs({ en: 'e1', at: 'name', vl: 'Alice' })
+		const joined = joinThreads([threadFrom(logsA, 'A'), threadFrom([], 'B')])
+
+		expect(joined.size).toBe(1)
+	})
+
+	it('handles joining a single thread', () => {
+		const logsA = makeLogs({ en: 'e1', at: 'name', vl: 'Alice' })
+		const joined = joinThreads([threadFrom(logsA, 'A')])
+
+		expect(joined.size).toBe(1)
+	})
+
+	it('merges three threads', () => {
+		const a = threadFrom(makeLogs({ en: 'e1', at: 'x', vl: 1 }), 'A')
+		const b = threadFrom(makeLogs({ en: 'e2', at: 'x', vl: 2 }), 'B')
+		const c = threadFrom(makeLogs({ en: 'e3', at: 'x', vl: 3 }), 'C')
+		const joined = joinThreads([a, b, c])
+
+		expect(joined.size).toBe(3)
+	})
+})
+
+// ═════════════════════════════════════════════════════════════════
+// Incremental updates (mapDelta — added)
+// ═════════════════════════════════════════════════════════════════
+
+describe('joinThreads — incremental adds', () => {
+	it('propagates new applog from one parent', () => {
+		const a = threadFrom(makeLogs({ en: 'e1', at: 'x', vl: 1 }), 'A')
+		const b = threadFrom([], 'B')
+		const joined = joinThreads([a, b])
+
+		expect(joined.size).toBe(1)
+
+		// Insert into B
+		const newLog = makeLog({ en: 'e2', at: 'x', vl: 2 })
+		b.insertRaw([newLog])
+
+		expect(joined.size).toBe(2)
+		expect(joined.applogs).toContain(newLog)
+	})
+
+	it('deduplicates when same log is added to second parent', () => {
+		const shared = makeLog({ en: 'e1', at: 'x', vl: 1 })
+		const a = threadFrom([shared], 'A')
+		const b = threadFrom([], 'B')
+		const joined = joinThreads([a, b])
+
+		expect(joined.size).toBe(1)
+
+		// Insert the same log into B — should not duplicate
+		b.insertRaw([shared])
+
+		expect(joined.size).toBe(1)
+	})
+
+	it('notifies subscribers on add', () => {
+		const a = threadFrom([], 'A')
+		const b = threadFrom([], 'B')
+		const joined = joinThreads([a, b])
+
+		const events: ThreadEvent[] = []
+		joined.subscribe(e => events.push(e))
+
+		const newLog = makeLog({ en: 'e1', at: 'x', vl: 1 })
+		a.insertRaw([newLog])
+
+		expect(events).toHaveLength(1)
+		expect(isInitEvent(events[0])).toBe(false)
+		if (!isInitEvent(events[0])) {
+			expect(events[0].added).toContain(newLog)
+		}
+	})
+
+	it('inserts maintain sort order', () => {
+		const early = makeLog({ en: 'e1', at: 'x', vl: 1, ts: '2020-01-01T00:00:00Z' })
+		const a = threadFrom([early], 'A')
+		const b = threadFrom([], 'B')
+		const joined = joinThreads([a, b])
+
+		const late = makeLog({ en: 'e2', at: 'x', vl: 2, ts: '2025-01-01T00:00:00Z' })
+		b.insertRaw([late])
+
+		expect(joined.applogs[0]).toBe(early)
+		expect(joined.applogs[1]).toBe(late)
+
+		// Now insert something in between
+		const mid = makeLog({ en: 'e3', at: 'x', vl: 3, ts: '2022-06-01T00:00:00Z' })
+		a.insertRaw([mid])
+
+		expect(joined.applogs[0]).toBe(early)
+		expect(joined.applogs[1]).toBe(mid)
+		expect(joined.applogs[2]).toBe(late)
+	})
+})
+
+// ═════════════════════════════════════════════════════════════════
+// setParents — swap input threads without new result reference
+// ═════════════════════════════════════════════════════════════════
+
+describe('joinThreads — setParents', () => {
+	it('replaces parents and recomputes', () => {
+		const a = threadFrom(makeLogs({ en: 'e1', at: 'x', vl: 1 }), 'A')
+		const b = threadFrom(makeLogs({ en: 'e2', at: 'x', vl: 2 }), 'B')
+		const joined = joinThreads([a, b])
+
+		expect(joined.size).toBe(2)
+
+		// Swap to a completely different set of parents
+		const c = threadFrom(makeLogs({ en: 'e3', at: 'x', vl: 3 }), 'C')
+		joined.setParents([c])
+
+		expect(joined.size).toBe(1)
+		expect(joined.applogs[0].vl).toBe(3)
+	})
+
+	it('notifies subscribers with init event on setParents', () => {
+		const a = threadFrom(makeLogs({ en: 'e1', at: 'x', vl: 1 }), 'A')
+		const joined = joinThreads([a])
+
+		const events: ThreadEvent[] = []
+		joined.subscribe(e => events.push(e))
+
+		const b = threadFrom(makeLogs({ en: 'e2', at: 'x', vl: 2 }), 'B')
+		joined.setParents([b])
+
+		expect(events).toHaveLength(1)
+		expect(isInitEvent(events[0])).toBe(true)
+	})
+
+	it('subscribes to new parents after setParents', () => {
+		const a = threadFrom(makeLogs({ en: 'e1', at: 'x', vl: 1 }), 'A')
+		const joined = joinThreads([a])
+
+		const b = threadFrom([], 'B')
+		joined.setParents([b])
+
+		expect(joined.size).toBe(0)
+
+		// Insert into new parent — should propagate
+		const newLog = makeLog({ en: 'e2', at: 'x', vl: 2 })
+		b.insertRaw([newLog])
+
+		expect(joined.size).toBe(1)
+		expect(joined.applogs).toContain(newLog)
+	})
+
+	it('unsubscribes from old parents after setParents', () => {
+		const a = threadFrom([], 'A')
+		const joined = joinThreads([a])
+
+		const events: ThreadEvent[] = []
+		joined.subscribe(e => events.push(e))
+
+		const b = threadFrom([], 'B')
+		joined.setParents([b])
+
+		// Clear the init event from setParents
+		events.length = 0
+
+		// Insert into OLD parent — should NOT propagate
+		a.insertRaw([makeLog({ en: 'e1', at: 'x', vl: 1 })])
+
+		expect(events).toHaveLength(0)
+		expect(joined.size).toBe(0)
+	})
+})
+
+// ═════════════════════════════════════════════════════════════════
+// triggerRemap — full recompute
+// ═════════════════════════════════════════════════════════════════
+
+describe('joinThreads — triggerRemap', () => {
+	it('recomputes from current parents', () => {
+		const a = threadFrom(makeLogs({ en: 'e1', at: 'x', vl: 1 }), 'A')
+		const b = threadFrom(makeLogs({ en: 'e2', at: 'x', vl: 2 }), 'B')
+		const joined = joinThreads([a, b])
+
+		expect(joined.size).toBe(2)
+
+		joined.triggerRemap()
+
+		expect(joined.size).toBe(2)
+	})
+
+	it('emits init event to subscribers', () => {
+		const a = threadFrom(makeLogs({ en: 'e1', at: 'x', vl: 1 }), 'A')
+		const joined = joinThreads([a])
+
+		const events: ThreadEvent[] = []
+		joined.subscribe(e => events.push(e))
+
+		joined.triggerRemap()
+
+		expect(events).toHaveLength(1)
+		expect(isInitEvent(events[0])).toBe(true)
+		if (isInitEvent(events[0])) {
+			expect(events[0].init).toHaveLength(1)
+		}
+	})
+})
+
+// ═════════════════════════════════════════════════════════════════
+// dispose
+// ═════════════════════════════════════════════════════════════════
+
+describe('joinThreads — dispose', () => {
+	it('stops receiving parent updates after dispose', () => {
+		const a = threadFrom([], 'A')
+		const joined = joinThreads([a])
+
+		const events: ThreadEvent[] = []
+		joined.subscribe(e => events.push(e))
+
+		joined.dispose()
+
+		a.insertRaw([makeLog({ en: 'e1', at: 'x', vl: 1 })])
+
+		// No events should have been received
+		expect(events).toHaveLength(0)
+	})
+})

package/src/thread/mapped.ts

@@ -0,0 +1,226 @@
+import { Logger } from 'besonders-logger'
+import { DebouncedFunc, pull, sortedIndexBy } from 'lodash-es'
+import { Applog, ApplogForInsert } from '../applog/datom-types.ts'
+import { arrayIfSingle } from '../types/typescript-utils.ts'
+import { isInitEvent, Thread, ThreadEvent } from './basic.ts'
+
+const { WARN, LOG, DEBUG, VERBOSE, ERROR } = Logger.setup(Logger.INFO) // eslint-disable-line no-unused-vars
+
+// ── ThreadDerivation ────────────────────────────────────────────
+
+/** Delta event — only incremental changes (no init) */
+export type DeltaEvent = { added: readonly Applog[], removed: readonly Applog[] | null }
+
+/** Context passed to mapDelta — explicit deps, no `this` needed */
+export interface DeltaContext {
+	/** The parent thread that emitted the delta */
+	source: Thread
+	/** All current parent threads */
+	parents: readonly Thread[]
+	/** The mapped thread's output before this delta is applied */
+	state: readonly Applog[]
+}
+
+/**
+ * Derivation for a MappedThread — separates full recomputation from incremental updates.
+ *
+ * - `compute` produces full state from parents (construction, reset, parent reinit)
+ * - `mapDelta` transforms a parent's incremental delta (optional — falls back to compute)
+ */
+export interface ThreadDerivation {
+	/** Compute full state from parents. Called at construction, triggerRemap, and parent reinit. */
+	compute(parents: readonly Thread[]): Applog[]
+
+	/**
+	 * Transform an incremental delta from a parent.
+	 * Return null to fall back to full recompute via compute().
+	 * Optional — if omitted, every parent change triggers compute().
+	 */
+	mapDelta?: (delta: DeltaEvent, ctx: DeltaContext) => DeltaEvent | null
+}
+
+// ── Write mapper (unchanged) ───────────────────────────────────
+
+// export type ApplogWriteMapper<T extends Applog[] | ApplogForInsert[]> = (this: MappedThread, applogs: T) => T | null // FIXME: the TS generics don't actually work how I want them to
+export type ApplogWriteMapper = (this: MappedThread, applogs: Applog[] | ApplogForInsert[]) => Applog[] | ApplogForInsert[] | null
+
+// ── MappedThread ───────────────────────────────────────────────
+
+export class MappedThread extends Thread {
+	static mapWrites(parent: Thread, name: string, mapper: ApplogWriteMapper) {
+		return new MappedThread(
+			`${name}<${parent.nameAndSizeUntracked}>`,
+			parent,
+			parent.filters,
+			null, // no derivation — share parent array
+			mapper,
+		)
+	}
+	static asReadOnly(parent: Thread) {
+		if (parent.readOnly) return parent // already read-only, no need to wrap
+		return new MappedThread(
+			`readOnly(${parent.name})`,
+			parent,
+			parent.filters,
+			null, // no derivation — share parent array
+			null,
+			true, // readOnly
+		)
+	}
+	private _parentSubscriptions: Map<Thread, (() => void)> = null // mapped to unsubscribe function
+
+	constructor(
+		readonly name: string,
+		parents: Thread | readonly Thread[],
+		filters: readonly string[],
+		private _derivation: ThreadDerivation | null,
+		private _writeMapper: ApplogWriteMapper = null,
+		private _readOnly?: boolean,
+	) {
+		const parentArr = arrayIfSingle(parents) as readonly Thread[]
+
+		if (!_derivation && parentArr.length > 1) {
+			throw new Error(`MappedThread without derivation must have exactly one parent`)
+		}
+
+		const initialLogs = _derivation
+			? _derivation.compute(parentArr)
+			: (parentArr[0] as any)._applogs as Applog[] // no derivation = share parent array
+
+		super(
+			name,
+			parents,
+			filters,
+			_derivation ? [...initialLogs] : initialLogs, // clone if derived, share if not
+		)
+
+		if (_derivation) {
+			this.subscribeToParents()
+		}
+	}
+
+	public insert(appLogsToInsert: ApplogForInsert[]) {
+		if (this.readOnly) throw ERROR(`[MappedThread] insert() called on read-only thread:`, this.nameAndSizeUntracked)
+		const mapped = this._writeMapper ? this._writeMapper(appLogsToInsert) : appLogsToInsert
+		if (this._writeMapper && !mapped) return
+		return this.parents.forEach(parent => parent.insert(mapped))
+	}
+	public insertRaw(appLogsToInsert: Applog[]) {
+		if (this.readOnly) throw ERROR(`[MappedThread] insertRaw() called on read-only thread:`, this.nameAndSizeUntracked)
+		const mapped = this._writeMapper ? this._writeMapper(appLogsToInsert) : appLogsToInsert
+		if (this._writeMapper && !mapped) return
+		return this.parents.forEach(parent => parent.insertRaw(mapped as Applog[]))
+	}
+
+	private subscribeToParents() {
+		this._parentSubscriptions = new Map()
+		if (!this.parents.length) {
+			WARN(`MappedThread has no parents`, this)
+		}
+		VERBOSE(`[MappedThread: ${this.name}] subscribing to parents:`, this.parents.map(p => p.name))
+
+		for (const p of this.parents) {
+			VERBOSE(`[MappedThread: ${this.name}] sub to parent`, p.nameAndSizeUntracked)
+			const sub = this.onParentUpdate.bind(this, p)
+			const unsubscribe = p.subscribe(sub, 'derived')
+			this._parentSubscriptions.set(p, unsubscribe)
+		}
+	}
+
+	/** Tear down parent subscriptions and clear internal state */
+	dispose() {
+		if (this._parentSubscriptions) {
+			for (const [, unsubscribe] of this._parentSubscriptions) {
+				unsubscribe()
+			}
+			this._parentSubscriptions = null
+		}
+	}
+
+	/** Swap parents at runtime — re-subscribes and recomputes applogs, notifying downstream */
+	setParents(newParents: readonly Thread[]) {
+		this.dispose()
+		;(this as { parents: readonly Thread[] }).parents = newParents
+		this.subscribeToParents()
+		this.triggerRemap()
+	}
+
+	subscribe(callback: (event: ThreadEvent) => void, type?: 'derived' | 'reaction') {
+		if (this._derivation && !this._parentSubscriptions) {
+			this.subscribeToParents()
+		}
+		return super.subscribe(callback, type)
+	}
+
+	/** Recompute full state from parents via compute() */
+	triggerRemap() {
+		if (!this._derivation) throw ERROR(`triggerRemap on a thread without derivation`, this.nameAndSizeUntracked)
+		DEBUG(`MappedThread{${this.nameAndSizeUntracked}} triggerRemap`)
+		const newLogs = this._derivation.compute(this.parents as readonly Thread[])
+		this._applogs.length = 0
+		this._applogs.push(...newLogs)
+		this.notifySubscribers({ init: newLogs })
+	}
+
+	protected onParentUpdate(sourceThread: Thread, event: ThreadEvent) {
+		if (!this._derivation) return // no derivation = shared array, parent handles it
+
+		VERBOSE(`MappedThread{${this.nameAndSizeUntracked}} parentUpdate`, event)
+
+		let result: ThreadEvent
+
+		if (isInitEvent(event)) {
+			// Parent reinit → full recompute (ignore payload, read current parent state)
+			const newLogs = this._derivation.compute(this.parents as readonly Thread[])
+			result = { init: newLogs }
+		} else if (this._derivation.mapDelta) {
+			const ctx: DeltaContext = {
+				source: sourceThread,
+				parents: this.parents as readonly Thread[],
+				state: this._applogs,
+			}
+			const mapped = this._derivation.mapDelta(event, ctx)
+			if (mapped === null) {
+				// mapDelta can't handle it → fall back to full recompute
+				const newLogs = this._derivation.compute(this.parents as readonly Thread[])
+				result = { init: newLogs }
+			} else {
+				result = mapped
+			}
+		} else {
+			// No mapDelta → always full recompute
+			const newLogs = this._derivation.compute(this.parents as readonly Thread[])
+			result = { init: newLogs }
+		}
+
+		// Apply result to _applogs
+		if (isInitEvent(result)) {
+			this._applogs.length = 0
+			this._applogs.push(...result.init)
+		} else {
+			VERBOSE(`MappedThread{${this.nameAndSizeUntracked}} parentUpdate => mapped`, result)
+			for (const log of result.added) {
+				// insert at right location to maintain sort order
+				this._applogs.splice(sortedIndexBy(this._applogs, log, 'ts'), 0, log)
+			}
+			if (result.removed) {
+				for (const toRemove of result.removed) {
+					const idx = this._applogs.indexOf(toRemove)
+					if (idx >= 0) {
+						this._applogs.splice(idx, 1)
+					} else {
+						throw ERROR(`MappedThread{${this.name}} toRemove: log not found`, toRemove, {
+							thread: this,
+							event,
+							result,
+						})
+					}
+				}
+			}
+		}
+		this.notifySubscribers(result)
+	}
+	get readOnly() {
+		return this._readOnly ?? false
+	}
+}

package/src/thread/utils.ts

@@ -0,0 +1,144 @@
+import { Logger } from 'besonders-logger'
+import { curry, debounce, partial, pull, uniq, uniqBy, uniqWith } from 'lodash-es'
+
+import { CID } from 'multiformats'
+import { ensureTsPvAndFinalizeApplogs, joinThreads } from '../applog/applog-helpers.ts'
+import { compareApplogsByEnAt, compareApplogsByTs, objEqualByKeys } from '../applog/applog-utils.ts'
+import { Applog, ApplogForInsert, CidString, EntityID } from '../applog/datom-types.ts'
+import { Thread } from './basic.ts'
+import { MappedThread } from './mapped.ts'
+import { ThreadInMemory, WriteableThread } from './writeable.ts'
+
+const { WARN, LOG, DEBUG, VERBOSE, ERROR } = Logger.setup(Logger.INFO) // eslint-disable-line no-unused-vars
+
+export function entityCount(thread: Thread) {
+	return allEntityIDs(thread).size // at some point: index size?
+}
+export function allEntityIDs(thread: Thread) {
+	return accumulateLogsToSet(thread, log => log.en)
+}
+
+function accumulateLogsToSet<ACC>(
+	threadOrLogs: Thread | Applog[],
+	callback: (log: Applog, acc: Set<ACC>) => ACC | undefined,
+) {
+	const logs = threadOrLogs instanceof Thread ? threadOrLogs.applogs : threadOrLogs
+	const set = new Set<ACC>()
+	for (const log of logs) {
+		set.add(callback(log, set))
+	}
+	return set
+}
+
+export function debounceWrites(
+	thread: Thread,
+	wait = 700,
+	removeDuplicatesWith = compareApplogsByEnAt,
+) {
+	if (thread.readOnly) throw ERROR(`[debounceWrites] but readOnly thread`, thread.name)
+	let insertQueue: Array<Applog | ApplogForInsert> = []
+
+	const debouncedCommit = debounce(() => {
+		WARN(`Debounce tail`, { thread, mappedThread, insertQueue })
+		const toInsert = ensureTsPvAndFinalizeApplogs(
+			// ? uniq, sure - but which one is used? (update: seems the first one, so reverse)
+			uniqWith(insertQueue.reverse(), removeDuplicatesWith),
+			thread,
+		)
+		thread.insertRaw(toInsert)
+		insertQueue.splice(0, insertQueue.length) // clear queue
+	}, wait)
+	const handleInsert = (applogs: Applog[] | ApplogForInsert[]) => {
+		DEBUG(`Debounce input:`, applogs, { thread, mappedThread, insertQueue })
+		insertQueue.push(...applogs)
+		debouncedCommit()
+		return null // don't insert anything
+	}
+
+	const mappedThread = MappedThread.mapWrites(
+		thread,
+		`Debounce(${wait})`,
+		handleInsert,
+	)
+	return mappedThread
+}
+
+/**
+ * @param deduplicateHoldItemsWith called with (heldLog, realLog), if it returns true, the held log is skipped
+ * @param onFirstWrite called with held logs about to be inserted, if it returns an array, those logs will be inserted instead
+ */
+export function holdTillFirstWrite(
+	thread: Thread,
+	applogsToHold: ApplogForInsert[],
+	opts: {
+		deduplicateHoldItemsWith?: typeof compareApplogsByEnAt
+		onFirstWrite: (heldLogsToInsert: Applog[]) => Applog[] | undefined
+	},
+) {
+	DEBUG(`[holdTillFirstWrite] holding logs:`, { applogsToHold })
+	if (thread.readOnly) throw ERROR(`[holdTillFirstWrite] but readOnly thread`, thread.nameAndSizeUntracked)
+	const heldLogs = ensureTsPvAndFinalizeApplogs([...applogsToHold], thread)
+	const heldThread = ThreadInMemory.fromArray(heldLogs)
+
+	let hasInserted = false
+	const handleInsert = (realApplogs: Applog[] | ApplogForInsert[]) => {
+		if (hasInserted) return realApplogs
+		hasInserted = true
+
+		let toInsert = [...heldLogs]
+		// heldLogs.splice(0, heldLogs.length) // ? joinThread could take care of this
+		if (opts.deduplicateHoldItemsWith) {
+			toInsert = toInsert.filter(heldLog =>
+				// some duplicate? so don't insert
+				!realApplogs.some(realLog => opts.deduplicateHoldItemsWith(heldLog, realLog))
+			)
+		}
+		if (opts.onFirstWrite) {
+			const callbackResult = opts.onFirstWrite(toInsert)
+			if (callbackResult !== undefined) {
+				toInsert = callbackResult
+			}
+		}
+		DEBUG(`[holdTillFirstWrite] adding hold logs:`, { applogsToHold, heldLogs, toInsert, realApplogs })
+		return [...toInsert, ...realApplogs]
+	}
+	const joinedThread = joinThreads([thread, heldThread])
+	return new MappedThread(
+		`HoldTillFirstWrite[${applogsToHold.length}]<${thread.nameAndSizeUntracked}>`,
+		joinedThread,
+		thread.filters,
+		null, // no derivation — shares joinedThread's array
+		(applogs) => {
+			const logsToInsert = handleInsert(applogs)
+			thread.insert(logsToInsert)
+			return null
+		},
+	)
+}
+
+export function getAgents(thread: Thread) {
+	return uniq(thread.map(l => l.ag))
+}
+
+/**
+ * Returns applogs NOT contained in the exclusion set.
+ * Uses CID-based comparison (consistent with removeDuplicateAppLogs).
+ */
+export const excludeApplogsContainedIn = (
+	applogs: readonly Applog[],
+	exclude: Thread | readonly Applog[] | Set<CID | CidString>,
+): Applog[] => {
+	const excludeCids: Set<string> = exclude instanceof Set
+		? new Set([...exclude].map(c => c.toString()))
+		: exclude instanceof Thread
+			? new Set(exclude.applogsCids)
+			: new Set(exclude.map(a => a.cid))
+
+	return applogs.filter(applog => {
+		if (!applog.cid) {
+			ERROR(`applog with missing CID`, applog)
+			throw new Error(`applog with missing CID`)
+		}
+		return !excludeCids.has(applog.cid)
+	})
+}