harper 5.1.20 → 5.2.0-alpha.5

package/resources/models/openaiStream.ts

@@ -0,0 +1,133 @@
+/**
+ * `openaiStream()` — format an internal `generateStream()` token iterator into the
+ * OpenAI-compatible Server-Sent Events shape so unmodified OpenAI / LangChain.js /
+ * Vercel AI SDK clients can consume a Harper chat-completions stream (#514, #510).
+ *
+ * The yielded `{ data }` messages pass through Harper's existing `text/event-stream`
+ * serializer (`server/serverHelpers/contentTypes.ts`) unchanged: an object `data`
+ * is JSON-stringified to `data: {json}\n\n`, and the terminal `{ data: '[DONE]' }`
+ * sentinel serializes to `data: [DONE]\n\n` — exactly OpenAI's wire format. We emit
+ * NO SSE `event:` or `id:` lines: OpenAI's stream is `data:`-only and the completion
+ * id lives inside the JSON payload, not as an SSE field.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { GenerateChunk, GenerateResult } from './types.ts';
+
+type OpenAIFinishReason = GenerateResult['finishReason'];
+
+export interface OpenAIStreamOptions {
+	/** Advertised model name echoed back on every chunk. */
+	model?: string;
+	/** Reuse a caller-supplied completion id across all chunks; one is generated when omitted. */
+	id?: string;
+}
+
+interface OpenAIToolCallDelta {
+	index: number;
+	id: string;
+	type: 'function';
+	function: { name: string; arguments: string };
+}
+
+interface OpenAIDelta {
+	role?: 'assistant';
+	content?: string;
+	tool_calls?: OpenAIToolCallDelta[];
+}
+
+interface OpenAIChunk {
+	id: string;
+	object: 'chat.completion.chunk';
+	created: number;
+	model: string;
+	choices: Array<{ index: number; delta: OpenAIDelta; finish_reason: OpenAIFinishReason | null }>;
+}
+
+/** SSE message envelope consumed by Harper's `text/event-stream` serializer. */
+export interface OpenAIStreamMessage {
+	data: OpenAIChunk | string;
+}
+
+/**
+ * Wrap a `GenerateChunk` async iterable as OpenAI `chat.completion.chunk` SSE messages,
+ * terminated by the `[DONE]` sentinel. Content deltas stream inline; tool calls are
+ * assembled and flushed once (see the tool-call note below).
+ */
+export async function* openaiStream(
+	tokens: AsyncIterable<GenerateChunk>,
+	opts: OpenAIStreamOptions = {}
+): AsyncGenerator<OpenAIStreamMessage> {
+	const id = opts.id ?? `chatcmpl-${randomUUID().replaceAll('-', '')}`;
+	const created = Math.floor(Date.now() / 1000);
+	const model = opts.model ?? '';
+
+	let roleSent = false;
+	let finishReason: OpenAIFinishReason | undefined;
+
+	// Tool-call assembly. Backends pre-parse arguments to objects and may re-send the
+	// same id with partial fields (see `mergeToolCallDelta` in agentLoop.ts), so we
+	// accumulate by id here and emit each call's arguments as ONE stringified blob.
+	// Emitting incremental fragments would corrupt the OpenAI client's concatenation
+	// (`{"a":1}` + `{"b":2}` → invalid JSON) — Harper's already-buffered upstream model
+	// means we cannot faithfully reproduce per-token argument fragments anyway.
+	const toolAssembly = new Map<string, { index: number; name?: string; arguments: object }>();
+
+	const chunk = (delta: OpenAIDelta, finish: OpenAIFinishReason | null): OpenAIStreamMessage => ({
+		data: {
+			id,
+			object: 'chat.completion.chunk',
+			created,
+			model,
+			choices: [{ index: 0, delta, finish_reason: finish }],
+		},
+	});
+
+	for await (const token of tokens) {
+		if (token.deltaContent !== undefined) {
+			const delta: OpenAIDelta = {};
+			if (!roleSent) {
+				delta.role = 'assistant';
+				roleSent = true;
+			}
+			delta.content = token.deltaContent;
+			yield chunk(delta, null);
+		}
+		if (token.deltaToolCalls) {
+			for (const incoming of token.deltaToolCalls) {
+				if (!incoming.id) continue;
+				const existing = toolAssembly.get(incoming.id) ?? { index: toolAssembly.size, arguments: {} };
+				if (incoming.name) existing.name = incoming.name;
+				if (incoming.arguments) existing.arguments = { ...existing.arguments, ...incoming.arguments };
+				toolAssembly.set(incoming.id, existing);
+			}
+		}
+		if (token.finishReason) finishReason = token.finishReason;
+	}
+
+	if (toolAssembly.size > 0) {
+		const toolCalls: OpenAIToolCallDelta[] = [];
+		for (const [callId, call] of toolAssembly) {
+			toolCalls.push({
+				index: call.index,
+				id: callId,
+				type: 'function',
+				function: { name: call.name ?? '', arguments: JSON.stringify(call.arguments) },
+			});
+		}
+		const delta: OpenAIDelta = {};
+		if (!roleSent) {
+			delta.role = 'assistant';
+			roleSent = true;
+		}
+		delta.tool_calls = toolCalls;
+		yield chunk(delta, null);
+	}
+
+	const finish: OpenAIFinishReason = finishReason ?? (toolAssembly.size > 0 ? 'tool_calls' : 'stop');
+	const terminalDelta: OpenAIDelta = {};
+	if (!roleSent) terminalDelta.role = 'assistant';
+	yield chunk(terminalDelta, finish);
+
+	yield { data: '[DONE]' };
+}

package/resources/replayLogs.ts

@@ -190,10 +190,11 @@ export function replayLogs(rootStore: RocksDatabase, tables: any): Promise<void>
 					transaction = new DatabaseTransaction();
 					transaction.db = primaryStore;
 					transaction.timestamp = version;
-					// we treat this as a retry, because it is (and we want to skip writing to the transaction log)
+					// retries=1 routes operation.commit() through its retry path (no duplicate audit staging)
 					transaction.retries = 1;
-					// Explicit replay marker so the write path skips schema validation (harper#1316). Keyed
-					// off this rather than `retries`, which conflict retries also bump and never reset.
+					// Explicit replay marker: skips schema validation (harper#1316) and makes save() stamp
+					// the native transaction isRetry, so replayed writes are never re-appended to the
+					// transaction log being iterated (re-appending would prevent replay convergence).
 					transaction.isReplay = true;
 				}
 				context.transaction = transaction;

package/resources/search.ts

@@ -2,7 +2,7 @@ import { ClientError, IndexRebuildingError, Violation } from '../utility/errors/
 import { OVERFLOW_MARKER, MAX_SEARCH_KEY_LENGTH, SEARCH_TYPES } from '../utility/lmdb/terms.ts';
 import { compareKeys, MAXIMUM_KEY } from 'ordered-binary';
 import { SKIP } from '@harperfast/extended-iterable';
-import { INVALIDATED, EVICTED } from './Table.ts';
+import { INVALIDATED, EVICTED, freezeRecord } from './Table.ts';
 import type { DirectCondition, Id } from './ResourceInterface.ts';
 import { RequestTarget } from './RequestTarget.ts';
 import { lastMetadata } from './RecordEncoder.ts';
@@ -44,8 +44,24 @@ export const COERCIBLE_OPERATORS = {
 	ne: true,
 	eq: true,
 };
-export function executeConditions(conditions, operator, table, txn, request, context, transformToEntries, filtered) {
+export function executeConditions(
+	conditions,
+	operator,
+	table,
+	txn,
+	request,
+	context,
+	transformToEntries,
+	filtered,
+	recordAccess?
+) {
 	const firstSearch = conditions[0];
+	// Record-level guards (a caller-supplied vectorFilter + RBAC allowReadRecord) apply to every record
+	// the query returns, independent of which condition leads (#1241). `recordAccess` is supplied only on
+	// the top-level executeConditions call (Table.search) and deliberately NOT threaded into the recursive
+	// calls below, so the guards run exactly once — on the final result set — rather than redundantly at
+	// each nested group.
+	const recordGuards = buildRecordGuards(recordAccess);
 	// both AND and OR start by getting an iterator for the ids for first condition
 	// and then things diverge...
 	if (operator === 'or') {
@@ -58,7 +74,7 @@ export function executeConditions(conditions, operator, table, txn, request, con
 			results = results.concat(nextResults);
 		}
 		const returnedIds = new Set();
-		return results.filter((entry) => {
+		const deduped = results.filter((entry) => {
 			const id = entry.key ?? entry;
 			if (returnedIds.has(id))
 				// skip duplicate ids
@@ -66,14 +82,35 @@ export function executeConditions(conditions, operator, table, txn, request, con
 			returnedIds.add(id);
 			return true;
 		});
+		// Record guards must hold on the OR union too — loading each surviving record and dropping the
+		// ones the guards reject (transformToEntries loads the record to evaluate a filter). Without this
+		// a record-level RBAC check would be bypassed by any OR query.
+		return recordGuards ? transformToEntries(deduped, recordGuards) : deduped;
 	} else {
-		// AND
+		// AND: use the indexed query for the first condition and filter by all subsequent conditions.
+		if (isFilterablePushdown(firstSearch, table)) {
+			// The lead is a filterable custom index (HNSW). It doesn't populate the join map (`filtered`)
+			// that sibling filters read, so — unlike the general case below — we can build the sibling
+			// filters BEFORE executing the lead and push them into the traversal, so filtering happens
+			// during the graph walk instead of post-filtering an under-filled candidate set (#1241). They
+			// also stay in the post-filter chain as a deterministic, harmless re-check.
+			const filters = mapConditionsToFilters(conditions.slice(1), true, firstSearch.estimated_count);
+			const recordFilters = recordGuards ? filters.concat(recordGuards) : filters;
+			// Execute a COPY carrying the pushed-down predicate, never mutating the caller's condition
+			// object (which may be reused across requests with different users / guards).
+			const lead =
+				recordFilters.length > 0
+					? { ...firstSearch, recordFilter: composeRecordFilter(recordFilters, table, context) }
+					: firstSearch;
+			const results = executeCondition(lead);
+			return recordFilters.length > 0 ? transformToEntries(results, recordFilters) : results;
+		}
+		// General path: execute the lead FIRST — a leading join populates `filtered`, which the sibling
+		// filters read as they are built — then apply the sibling filters plus any record guards.
 		const results = executeCondition(firstSearch);
-		// get the intersection of condition searches by using the indexed query for the first condition
-		// and then filtering by all subsequent conditions.
-		// now apply filters that require looking up records
 		const filters = mapConditionsToFilters(conditions.slice(1), true, firstSearch.estimated_count);
-		return filters.length > 0 ? transformToEntries(results, filters) : results;
+		const recordFilters = recordGuards ? filters.concat(recordGuards) : filters;
+		return recordFilters.length > 0 ? transformToEntries(results, recordFilters) : results;
 	}
 	function executeCondition(condition) {
 		if (condition.conditions)
@@ -86,6 +123,7 @@ export function executeConditions(conditions, operator, table, txn, request, con
 				context,
 				transformToEntries,
 				filtered
+				// recordAccess intentionally omitted: guards run once, at the top level (see above).
 			);
 		return searchByIndex(
 			condition,
@@ -122,6 +160,65 @@ export function executeConditions(conditions, operator, table, txn, request, con
 	}
 }
 
+/**
+ * Build the record-level guards that apply to a query independent of its conditions (#1241):
+ *   - `vectorFilter`: a caller-supplied `(record) => boolean` predicate (JS-API only).
+ *   - `allowReadRecord`: a resource's static record-level RBAC check `(user, record) => boolean`.
+ * Both arrive already resolved on `recordAccess` (assembled once in Table.search). Returns an array of
+ * `(record) => boolean` predicates, or undefined when neither is defined (the common case — zero
+ * overhead). Predicates must be synchronous and side-effect free; records passed in are frozen.
+ */
+function buildRecordGuards(recordAccess): ((record: any) => boolean)[] | undefined {
+	if (!recordAccess) return undefined;
+	const guards: ((record: any) => boolean)[] = [];
+	const vectorFilter = recordAccess.vectorFilter;
+	if (typeof vectorFilter === 'function') guards.push((record) => vectorFilter(record));
+	const allowReadRecord = recordAccess.allowReadRecord;
+	if (typeof allowReadRecord === 'function') {
+		const user = recordAccess.user;
+		guards.push((record) => allowReadRecord(user, record));
+	}
+	return guards.length > 0 ? guards : undefined;
+}
+
+/** True when a condition's index is a custom index that participates in predicate-aware traversal (HNSW). */
+function isFilterablePushdown(condition, table): boolean {
+	const attributeName = condition?.attribute ?? condition?.[0];
+	if (attributeName == null || table == null) return false;
+	const index = attributeName === table.primaryKey ? table.primaryStore : table.indices?.[attributeName];
+	return Boolean(index?.customIndex?.filteredSearch);
+}
+
+/**
+ * Compose a set of record predicates into the single `(primaryKey) => boolean` the custom index calls
+ * during traversal (#1241). The record is loaded lazily (only when the index reaches a node) via
+ * `primaryStore.getEntry` and frozen before the predicates see it. Verdicts are memoized per query since
+ * the graph can reach a node from multiple neighbors. A missing/deleted record fails the predicate.
+ */
+function composeRecordFilter(recordFilters, table, context): (primaryKey: Id) => boolean {
+	const memo = new Map<Id, boolean>();
+	const transaction = context && table._readTxnForContext ? table._readTxnForContext(context) : undefined;
+	return (primaryKey: Id) => {
+		const cached = memo.get(primaryKey);
+		if (cached !== undefined) return cached;
+		let verdict = false;
+		const entry = table.primaryStore.getEntry(primaryKey, { transaction });
+		const record = entry?.value;
+		if (record != null) {
+			freezeRecord(record);
+			verdict = true;
+			for (const filter of recordFilters) {
+				if (!filter(record, entry)) {
+					verdict = false;
+					break;
+				}
+			}
+		}
+		memo.set(primaryKey, verdict);
+		return verdict;
+	};
+}
+
 /**
  * Search for records or keys, based on the search condition, using an index if available
  * @param searchCondition
@@ -375,7 +472,7 @@ export function searchByIndex(
 						let result: any;
 						if (entry.value == null && !(entry.metadataFlags & (INVALIDATED | EVICTED))) result = SKIP;
 						else {
-							Object.freeze(entry.value);
+							freezeRecord(entry.value);
 							recordRead(entry);
 							result = entry;
 						}
@@ -387,7 +484,12 @@ export function searchByIndex(
 		return results;
 	} else if (index && !skipIndex) {
 		if (index.customIndex) {
-			const loaded = index.customIndex.search(searchCondition, context).map((entry) => {
+			// Predicate-aware traversal (#1241): a record filter composed from companion AND conditions,
+			// a caller-supplied vectorFilter, and record-level RBAC is pushed into the index so it keeps
+			// exploring until it has enough MATCHING results, rather than post-filtering an under-filled
+			// candidate set. Only indexes that opt in (filteredSearch) receive it; others post-filter as before.
+			const recordFilter = index.customIndex.filteredSearch ? searchCondition.recordFilter : undefined;
+			const loaded = index.customIndex.search(searchCondition, context, recordFilter).map((entry) => {
 				// if the custom index returns an entry with metadata, merge it with the loaded entry
 				if (typeof entry === 'object' && entry) {
 					const { key, ...otherProps } = entry;
@@ -396,7 +498,7 @@ export function searchByIndex(
 						transaction: context && Table._readTxnForContext(context),
 					});
 					if (!loadedEntry) return SKIP; // record was deleted/expired or not yet visible
-					Object.freeze(loadedEntry?.value);
+					freezeRecord(loadedEntry?.value);
 					recordRead(loadedEntry);
 					return { ...otherProps, ...loadedEntry };
 				}

package/resources/secretDecryptor.ts

@@ -0,0 +1,159 @@
+/**
+ * Extension point for decrypting `enc:v1:` secret values at runtime. `.env` loading is the first
+ * consumer; the same hook serves any store of `enc:v1:` ciphertext (secret tables, deploy
+ * credentials) so key custody stays in one place.
+ *
+ * Core (Apache) ships NO decryptor: encrypted values stay opaque and are skipped at load time.
+ * The Harper Pro secrets component registers a real decryptor here at startup (it holds the
+ * cluster's secrets private key), at which point consumers like `loadEnv` transparently decrypt
+ * encrypted values. Without Pro the hook is empty and the feature is dormant.
+ *
+ * The decryptor is synchronous on purpose — `loadEnv` runs synchronously and Node's RSA/AES
+ * primitives are synchronous, so this avoids reworking the load path. It receives the full value
+ * (including the `enc:v1:` prefix) and returns the plaintext, or throws if it cannot decrypt.
+ *
+ * Registration is per-process: the Pro component registers in each worker where secrets are
+ * consumed, so registration and use share the same module instance.
+ *
+ * Registration order is NOT load-bearing for `.env` values: entries that load before a decryptor
+ * exists are queued (see `deferEncryptedEnvValue`) and replayed into `process.env` the moment one
+ * registers, so a custody provider that comes up after component `.env` loading heals the skipped
+ * values instead of leaving them missing.
+ */
+import logger from '../utility/logging/harper_logger.ts';
+
+export type SecretDecryptor = (value: string) => string;
+
+/** An encrypted `.env` entry that was loaded before any decryptor was registered. */
+export interface DeferredEncryptedEnvValue {
+	key: string;
+	rawValue: string;
+	sourcePath: string;
+	override: boolean;
+}
+
+// Defensive cap: the queue only ever holds encrypted `.env` entries loaded before registration,
+// so growth beyond this indicates a bug or abuse — drop (with an error) rather than grow.
+const MAX_DEFERRED_SECRETS = 1000;
+let deferredSecrets: DeferredEncryptedEnvValue[] = [];
+
+let decryptor: SecretDecryptor | undefined;
+
+/**
+ * Queue an encrypted `.env` entry that could not be decrypted because no decryptor is registered
+ * yet. When one registers, the queue is replayed into `process.env` with the same
+ * override/conflict semantics `loadEnv` applied to the original load.
+ */
+export function deferEncryptedEnvValue(entry: DeferredEncryptedEnvValue): void {
+	// A re-evaluated env file (reload, watcher re-add) defers the same key again: replace the
+	// earlier entry in place so the queue holds one entry per {key, sourcePath} with the newest
+	// ciphertext, instead of wasting the cap and replaying stale values.
+	const existingIndex = deferredSecrets.findIndex(
+		(queued) => queued.key === entry.key && queued.sourcePath === entry.sourcePath
+	);
+	if (existingIndex >= 0) {
+		deferredSecrets[existingIndex] = entry;
+		return;
+	}
+	if (deferredSecrets.length >= MAX_DEFERRED_SECRETS) {
+		logger.error(
+			`Deferred encrypted env queue is full (${MAX_DEFERRED_SECRETS}); dropping ${entry.key} from ${entry.sourcePath}`
+		);
+		return;
+	}
+	deferredSecrets.push(entry);
+}
+
+/**
+ * A redacted snapshot of the queued entries awaiting a decryptor, for tests/diagnostics: a copy,
+ * without the ciphertext (`rawValue`), so holders can neither mutate pending entries nor retain
+ * the queued values past the flush.
+ */
+export function getDeferredEncryptedEnvValues(): Omit<DeferredEncryptedEnvValue, 'rawValue'>[] {
+	return deferredSecrets.map(({ key, sourcePath, override }) => ({ key, sourcePath, override }));
+}
+
+// Replay queued encrypted env entries through a newly registered decryptor, mirroring loadEnv's
+// conflict semantics: a failed decrypt logs and skips that entry; an already-set key is only
+// overwritten when the entry's env file was loaded with `override`.
+function replayDeferredSecrets(newDecryptor: SecretDecryptor): void {
+	const entries = deferredSecrets;
+	deferredSecrets = [];
+	for (const { key, rawValue, sourcePath, override } of entries) {
+		let value: string;
+		try {
+			value = newDecryptor(rawValue);
+		} catch (error) {
+			logger.error(
+				`Failed to decrypt deferred environment variable ${key} from ${sourcePath}: ${(error as Error).message}; skipping`
+			);
+			continue;
+		}
+		if (process.env[key] !== undefined) {
+			if (process.env[key] === value) continue; // already holds the decrypted value — nothing to report
+			logger.warn(`Environment variable conflict: ${key} from ${sourcePath} is already set on process.env`);
+			if (!override) continue;
+		}
+		process.env[key] = value;
+	}
+}
+
+/**
+ * Install the env-secret decryptor (called by the Pro env-secrets component at startup). Any
+ * encrypted `.env` entries that loaded before this point are immediately decrypted into
+ * `process.env`.
+ */
+export function registerSecretDecryptor(fn: SecretDecryptor): void {
+	decryptor = fn;
+	replayDeferredSecrets(fn);
+}
+
+/** The registered decryptor, or undefined when no Pro env-secrets component is active. */
+export function getSecretDecryptor(): SecretDecryptor | undefined {
+	return decryptor;
+}
+
+/** Remove the registered decryptor and drop any deferred entries. Intended for tests. */
+export function clearSecretDecryptor(): void {
+	decryptor = undefined;
+	deferredSecrets = [];
+}
+
+/** The public half of the cluster secrets keypair, with its stable SHA-256 fingerprint (`kid`). */
+export interface SecretCustodyPublicKey {
+	publicKey: string;
+	fingerprint: string;
+}
+
+/**
+ * Full key custody: decrypt plus access to the public key, so the node can encrypt on ingest
+ * (`set_secret` with a plaintext value) and serve `get_secrets_public_key`. Core ships no custody;
+ * the Pro secrets component registers one per process where secrets are used — including the MAIN
+ * thread, where the operations API dispatches the secret operations.
+ */
+export interface SecretCustody {
+	decrypt: SecretDecryptor;
+	getPublicKey(): SecretCustodyPublicKey;
+}
+
+let custody: SecretCustody | undefined;
+
+/**
+ * Install key custody. Also installs `custody.decrypt` via the decryptor slot above, so consumers
+ * like `loadEnv` that only need decryption keep working through the existing hook.
+ */
+export function registerSecretCustody(newCustody: SecretCustody): void {
+	custody = newCustody;
+	registerSecretDecryptor(newCustody.decrypt);
+}
+
+/** The registered custody, or undefined when no secrets key is held by this process. */
+export function getSecretCustody(): SecretCustody | undefined {
+	return custody;
+}
+
+/** Remove the registered custody (and the decryptor it installed). Intended for tests. */
+export function clearSecretCustody(): void {
+	custody = undefined;
+	decryptor = undefined;
+}

package/resources/tracked.ts

@@ -1,6 +1,7 @@
 import { ClientError } from '../utility/errors/hdbError.ts';
 import * as crdtOperations from './crdt.ts';
 import { Blob } from './blob.ts';
+import * as harperLogger from '../utility/logging/harper_logger.ts';
 
 function getChanges(target) {
 	let changes = target.getChanges();
@@ -59,13 +60,11 @@ export function assignTrackedAccessors(Target, typeDef, useFullPropertyProxy = f
 					break;
 				case 'ID':
 					set = function (value) {
-						if (
-							!(
-								typeof value === 'string' ||
-								(value?.length > 0 && value.every?.((value) => typeof value === 'string')) ||
-								(value == null && attribute.nullable !== false)
-							)
-						)
+						if (!(
+							typeof value === 'string' ||
+							(value?.length > 0 && value.every?.((value) => typeof value === 'string')) ||
+							(value == null && attribute.nullable !== false)
+						))
 							throw new ClientError(`${name} must be a string, attempt to assign ${value}`);
 						getChanges(this)[name] = value;
 					};
@@ -99,12 +98,10 @@ export function assignTrackedAccessors(Target, typeDef, useFullPropertyProxy = f
 				case 'Long':
 					set = function (value) {
 						let scalarValue = value?.__op__ ? value.value : value;
-						if (
-							!(
-								(Math.round(scalarValue) === value && Math.abs(scalarValue) <= 9007199254740992) ||
-								(value == null && attribute.nullable !== false)
-							)
-						) {
+						if (!(
+							(Math.round(scalarValue) === value && Math.abs(scalarValue) <= 9007199254740992) ||
+							(value == null && attribute.nullable !== false)
+						)) {
 							if (typeof scalarValue === 'number' && Math.abs(scalarValue) <= 9007199254740992) {
 								// if it just needs to be rounded, do the conversion without complaining
 								scalarValue = Math.round(scalarValue);
@@ -427,9 +424,18 @@ export function updateAndFreeze(target, changes = target.getChanges?.()) {
 		let value = changes[key];
 		if (value && typeof value === 'object') {
 			if (value.__op__) {
-				const operation = crdtOperations[value?.__op__];
-				if (!operation) throw new Error('Invalid CRDT operation ' + value.__op__);
-				else operation(mergedUpdatedObject, key, value);
+				// Resolve against the explicit operation registry, not the crdt.ts export namespace,
+				// so a crafted/corrupt `__op__` naming another export can't be invoked as an operation.
+				const operation = crdtOperations.operations[value.__op__];
+				if (operation) operation(mergedUpdatedObject, key, value);
+				else {
+					// An unrecognized CRDT operation — corruption, or an op type from a newer node this
+					// version can't apply. This runs on the write/replication apply path, where throwing
+					// would abort the commit and can wedge a subscription, so skip the op instead: the
+					// field keeps its base value and a full-copy re-converges the record. Read-path
+					// reconstruction (crdt.applyForward/applyReverse) still throws loudly by design.
+					harperLogger.warn(`Skipping unrecognized CRDT operation "${value.__op__}" on property "${key}"`);
+				}
 				continue;
 			} else value = updateAndFreeze(value);
 		}
@@ -588,6 +594,7 @@ export class Addition {
 		this.value = value;
 	}
 	update(previousValue) {
-		return (+previousValue || 0) + this.value;
+		// Shared with crdt.add so the read path folds identically to the storage path.
+		return crdtOperations.addValues(previousValue, this.value);
 	}
 }