@mastra/clickhouse 1.21.0 → 1.21.1-alpha.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-clickhouse
 description: Documentation for @mastra/clickhouse. Use when working with @mastra/clickhouse APIs, configuration, or implementation.
 metadata:
   package: "@mastra/clickhouse"
-  version: "1.21.0"
+  version: "1.21.1-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.21.0",
+  "version": "1.21.1-alpha.0",
   "package": "@mastra/clickhouse",
   "exports": {},
   "modules": {}

package/dist/docs/references/integrations-databases-clickhouse.md

@@ -93,9 +93,7 @@ Lightweight deletion is a hide-only operation that marks rows with ClickHouse's
 
 When all five observability signals have finite retention, Mastra also applies a TTL to deletion requests so they outlive the signal rows they protect. If any signal is unbounded, deletion requests remain unbounded. See [storage retention](https://mastra.ai/reference/storage/retention) for how the deletion-request TTL is calculated.
 
-Feedback review-status updates require `ALTER UPDATE` permission on `mastra_feedback_events` and, when delta polling is enabled, `INSERT` permission on `mastra_feedback_events_delta`. These updates wait for the ClickHouse mutation to finish on the server that receives the write, so latency depends on that server's mutation queue. Other replicas apply the mutation through the replication log, so a reader on a lagging replica can briefly see the previous status, and an inactive replica doesn't block the update. They modify the existing feedback row and preserve deletion masks: a concurrent review update cannot recreate deleted feedback. Successful updates remain available through delta polling. If a newer version of the same feedback event is ingested while a review update is in flight, the update is re-applied to that newer version; after repeated conflicts it fails with a conflict error (HTTP 409) and the caller retries.
-
-The status mutation and the delta insert are separate operations. If the delta insert fails, the API returns an error even though the status may have changed, and continued delta polling doesn't recover that notification: later polls from the same cursor never return it, and starting delta mode without a cursor subscribes at the current head. To recover, retry the review update after resolving the error, or reread the feedback with a regular list query.
+Feedback review-status updates read the current row and insert a replacement, so they need `SELECT` and `INSERT` rather than `ALTER UPDATE`, and the insert materialized view publishes each update to delta polling. An update that re-runs a delete also needs the delete permissions listed in [initialization](#initialization). A review update that lands while a delete of the same feedback is in progress re-runs that delete and returns not found, so it can't recreate deleted feedback. A failed delete doesn't block review updates, but the next update retries it: if the retry succeeds, the update returns not found; if it fails again, the new status is saved but the update returns the delete's error. If a network error or a lagging replica lets a review row outlive a successful delete, the next review update of that feedback deletes it again and returns not found.
 
 ### Observability with the legacy domain
 
@@ -372,16 +370,10 @@ const observability = new ObservabilityStorageClickhouseVNext({
 await observability.init()
 ```
 
-In CI/CD pipelines, set `disableInit: true` on `ClickhouseStore` and run `init()` from a deployment step that uses elevated credentials. Runtime application credentials still need more than read and insert:
+In CI/CD pipelines, set `disableInit: true` on `ClickhouseStore` and run `init()` from a deployment step that uses elevated credentials. Runtime application credentials need:
 
 - `SELECT` and `INSERT` on the Mastra tables.
 - `ALTER DELETE` on the observability tables you delete from. On ClickHouse 26.6 and earlier, lightweight deletes also require `ALTER UPDATE` on those tables; ClickHouse 26.7 removed that requirement.
-- For feedback review updates, `ALTER UPDATE(reviewStatus)` on `mastra_feedback_events` and `INSERT` on `mastra_feedback_events_delta`.
-
-```sql
-GRANT ALTER UPDATE(reviewStatus) ON <database>.mastra_feedback_events TO <runtime_user>;
-GRANT INSERT ON <database>.mastra_feedback_events_delta TO <runtime_user>;
-```
 
 ## Observability
 

package/dist/index.cjs

@@ -4879,29 +4879,16 @@ function feedbackNotFoundError(feedbackId) {
 		details: { feedbackId }
 	});
 }
-function feedbackConflictError(feedbackId) {
-	return new _mastra_core_error.MastraError({
-		id: "OBSERVABILITY_UPDATE_FEEDBACK_REVIEW_STATUS_CONFLICT",
-		domain: _mastra_core_error.ErrorDomain.MASTRA_OBSERVABILITY,
-		category: _mastra_core_error.ErrorCategory.USER,
-		text: "Feedback record changed while its review status was being updated; retry the update",
-		details: { feedbackId }
-	});
-}
-/** Re-reads before giving up when ingestion keeps superseding the observed row. */
-const REVIEW_UPDATE_ATTEMPTS = 3;
 /**
-* Only applied requests block a review update. The guard decides the reply,
-* not data safety: the update mutates the row in place and preserves the
-* delete mask, so a replica that has not received a marker yet can only
-* mis-report a status, never bring deleted feedback back.
+* Finds a deletion request covering this feedback. With `appliedOnly`, only
+* requests whose DELETE succeeded count; otherwise pending requests count too,
+* including a delete that is still running or one that failed.
 */
-async function hasFeedbackDeletionRequest(client, feedbackId, organizationId, resourceId) {
+async function hasFeedbackDeletionRequest(client, feedbackId, organizationId, resourceId, { appliedOnly }) {
 	return (await queryJson$2(client, `SELECT 1 AS found FROM ${TABLE_DELETION_REQUESTS} FINAL
      WHERE signal = 'feedback'
        AND predicateType = 'itemIds'
-       AND has(predicateValues, {feedbackId:String})
-       AND lastAppliedAt > toDateTime64(0, 3)
+       AND has(predicateValues, {feedbackId:String})${appliedOnly ? "\n       AND lastAppliedAt > toDateTime64(0, 3)" : ""}
        AND (organizationId = '' OR organizationId = {organizationId:String})
        AND (resourceId = '' OR resourceId = {resourceId:String})
      LIMIT 1`, {
@@ -4910,63 +4897,44 @@ async function hasFeedbackDeletionRequest(client, feedbackId, organizationId, re
 		resourceId: resourceId ?? ""
 	})).length > 0;
 }
-async function updateFeedbackReviewStatus(client, args, strategy = null) {
-	const { feedbackId, reviewStatus } = parseUpdateFeedbackReviewStatusArgs(args);
-	for (let attempt = 1;; attempt++) {
-		const updated = await applyReviewStatus(client, feedbackId, reviewStatus, strategy);
-		if (updated) return updated;
-		if (attempt >= REVIEW_UPDATE_ATTEMPTS) throw feedbackConflictError(feedbackId);
-	}
-}
 /**
-* One read-guard-mutate-verify pass. Returns `null` when the read-back does not
-* show the new status: a newer version superseded the observed row, a delete
-* hid it after the guard read (the next pass then reports not found), or the
-* mutation left the row untouched.
+* Review updates insert a replacement row, so they need only `INSERT` and the
+* insert materialized view publishes the delta cursor.
+*
+* A replacement written after a concurrent DELETE is not covered by that
+* DELETE. The post-write check therefore looks for any request, pending or
+* applied, and re-runs the delete when it finds one. Only applied requests
+* block the update up front, so feedback whose delete failed stays editable.
+*
+* If the post-write check reads a replica that has not received the request
+* yet, or the check or its delete fails, the replacement stays visible. A row
+* that is still visible under an applied request can only be such a leftover,
+* so the next update deletes it again.
 */
-async function applyReviewStatus(client, feedbackId, reviewStatus, strategy) {
-	const existingRow = (await queryJson$2(client, `SELECT *, toString(writeVersion) AS reviewWriteVersion FROM ${TABLE_FEEDBACK_EVENTS} FINAL
+async function updateFeedbackReviewStatus(client, args, replication) {
+	const { feedbackId, reviewStatus } = parseUpdateFeedbackReviewStatusArgs(args);
+	const existingRow = (await queryJson$2(client, `SELECT * FROM ${TABLE_FEEDBACK_EVENTS} FINAL
      WHERE feedbackId = {feedbackId:String}
      ORDER BY writeVersion DESC, timestamp DESC
      LIMIT 1`, { feedbackId }))[0];
 	if (!existingRow) throw feedbackNotFoundError(feedbackId);
-	if (await hasFeedbackDeletionRequest(client, feedbackId, existingRow.organizationId, existingRow.resourceId)) throw feedbackNotFoundError(feedbackId);
-	const identity = `feedbackId = {feedbackId:String}
-    AND timestamp = parseDateTime64BestEffort({timestamp:String}, 3, 'UTC')
-    AND (traceId = {traceId:Nullable(String)} OR (isNull(traceId) AND isNull({traceId:Nullable(String)})))
-    AND writeVersion = {writeVersion:UInt64}`;
-	const params = {
-		feedbackId,
-		timestamp: existingRow.timestamp,
-		traceId: existingRow.traceId,
-		writeVersion: existingRow.reviewWriteVersion,
-		reviewStatus
+	const { organizationId, resourceId } = existingRow;
+	const redelete = async () => {
+		await deleteFeedback(client, {
+			feedbackIds: [feedbackId],
+			organizationId: organizationId ?? void 0,
+			resourceId: resourceId ?? void 0
+		}, replication);
+		throw feedbackNotFoundError(feedbackId);
 	};
-	await client.command({
-		query: `ALTER TABLE ${TABLE_FEEDBACK_EVENTS} UPDATE reviewStatus = {reviewStatus:String} WHERE ${identity}`,
-		query_params: params,
-		clickhouse_settings: {
-			...CH_SETTINGS,
-			mutations_sync: "1"
-		}
-	});
-	if (strategy !== null) await client.command({
-		query: `INSERT INTO ${TABLE_FEEDBACK_EVENTS_DELTA}
-        SELECT ${buildDeltaCursorExpr(strategy, "mastra_feedback_events_delta_cursor", "feedbackId")} AS cursorId,
-          ingestedAt, traceId, timestamp, feedbackId
-        FROM (
-          SELECT now64(9, 'UTC') AS ingestedAt, traceId, timestamp, feedbackId
-          FROM ${TABLE_FEEDBACK_EVENTS} FINAL WHERE ${identity}
-        )`,
-		query_params: params,
-		clickhouse_settings: {
-			...CH_INSERT_SETTINGS,
-			async_insert: 0
-		}
+	if (await hasFeedbackDeletionRequest(client, feedbackId, organizationId, resourceId, { appliedOnly: true })) return redelete();
+	const updated = rowToFeedbackRecord({
+		...existingRow,
+		reviewStatus
 	});
-	if (await hasFeedbackDeletionRequest(client, feedbackId, existingRow.organizationId, existingRow.resourceId)) throw feedbackNotFoundError(feedbackId);
-	const current = await queryJson$2(client, `SELECT * FROM ${TABLE_FEEDBACK_EVENTS} FINAL WHERE ${identity} LIMIT 1`, params);
-	return current[0]?.reviewStatus === reviewStatus ? rowToFeedbackRecord(current[0]) : null;
+	await batchCreateFeedback(client, { feedbacks: [updated] });
+	if (await hasFeedbackDeletionRequest(client, feedbackId, organizationId, resourceId, { appliedOnly: false })) return redelete();
+	return updated;
 }
 async function listFeedback(client, args, strategy) {
 	const parsed = _mastra_core_storage.listFeedbackArgsSchema.parse(args);
@@ -8665,21 +8633,35 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 		if (!deltaPollingSupported(this.#deltaCursorStrategy)) return [
 			"metrics",
 			"logs",
+			"entity-type-discovery",
+			"entity-name-discovery",
+			"service-name-discovery",
+			"environment-discovery",
+			"tag-discovery",
+			"metric-discovery",
 			"trace-query",
 			"trace-query-root-duration",
 			"trace-query-discovery",
 			"thread-query",
-			"trace-query-tenant-scope"
+			"trace-query-tenant-scope",
+			"feedback"
 		];
 		return [
 			"metrics",
 			"logs",
+			"entity-type-discovery",
+			"entity-name-discovery",
+			"service-name-discovery",
+			"environment-discovery",
+			"tag-discovery",
+			"metric-discovery",
 			"delta-polling",
 			"trace-query",
 			"trace-query-root-duration",
 			"trace-query-discovery",
 			"thread-query",
-			"trace-query-tenant-scope"
+			"trace-query-tenant-scope",
+			"feedback"
 		];
 	}
 	async createSpan(args) {
@@ -9019,7 +9001,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 	}
 	async updateFeedbackReviewStatus(args) {
 		try {
-			return await updateFeedbackReviewStatus(this.#client, args, deltaPollingSupported(this.#deltaCursorStrategy) ? this.#deltaCursorStrategy : null);
+			return await updateFeedbackReviewStatus(this.#client, args, this.#replication);
 		} catch (error) {
 			if (error instanceof _mastra_core_error.MastraError) throw error;
 			throw new _mastra_core_error.MastraError({