@voltro/kv 0.86.0 → 0.87.0

package/dist/analytics.d.ts

@@ -0,0 +1,337 @@
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+export declare interface AggregateQuery {
+    readonly event: string;
+    readonly filter?: PropertyFilter;
+    readonly metric: AnalyticsMetric;
+    readonly range: TimeRange;
+    /**
+     * Restrict the read to one tenant's events. `useAnalytics()` injects the
+     * caller's `subject.tenantId` automatically, so handler code never sets
+     * this; a sink that honours it (e.g. analytics-postgres) then AND-filters
+     * by tenant so a query can't read across tenants. `null`/absent = unscoped
+     * (system/cross-tenant read).
+     */
+    readonly tenantId?: string | null;
+}
+
+export declare interface AnalyticsBucket {
+    readonly bucketStart: Date;
+    readonly value: number;
+}
+
+/**
+ * The sink doesn't implement this capability. PostHog returns this
+ * for `aggregate`/`timeseries`/`topN`. Callers typically
+ * `Effect.catchTag('AnalyticsCapabilityNotSupported', ...)` to fall
+ * back to a different sink or report the missing feature.
+ */
+export declare class AnalyticsCapabilityNotSupported extends AnalyticsCapabilityNotSupported_base {
+}
+
+declare const AnalyticsCapabilityNotSupported_base: Schema.Class<AnalyticsCapabilityNotSupported, Schema.TaggedStruct<"AnalyticsCapabilityNotSupported", {
+    readonly provider: Schema.String;
+    readonly capability: Schema.String;
+}>, YieldableError>;
+
+declare interface AnalyticsConnectionBatch {
+    readonly maxSize?: number;
+    readonly flushIntervalMs?: number;
+}
+
+export declare type AnalyticsConnectionConfig = AnalyticsOptions & ConnectionMetadata & {
+    readonly source?: 'config' | 'environment' | 'override';
+};
+
+export declare type AnalyticsConnectionConnector = (config: AnalyticsConnectionConfig) => Effect.Effect<AnalyticsConnectionTransport, KvError>;
+
+/** Physical transport returned only to the registry, never to a consumer. */
+export declare interface AnalyticsConnectionTransport {
+    readonly sink: AnalyticsSinkImpl;
+    readonly probe: Effect.Effect<void, KvError>;
+    readonly close: Effect.Effect<void>;
+}
+
+/**
+ * The underlying sink raised an error. `cause` is stringified for
+ * round-trip safety across the rpc boundary.
+ */
+export declare class AnalyticsError extends AnalyticsError_base {
+    get message(): string;
+}
+
+declare const AnalyticsError_base: Schema.Class<AnalyticsError, Schema.TaggedStruct<"AnalyticsError", {
+    readonly provider: Schema.String;
+    readonly operation: Schema.String;
+    readonly cause: Schema.String;
+}>, YieldableError>;
+
+/**
+ * One analytics event. `properties` must be JSON-serialisable —
+ * individual sinks validate at write time (Postgres stores as JSONB;
+ * ClickHouse encodes as a JSON string; PostHog forwards verbatim).
+ */
+export declare interface AnalyticsEvent {
+    /** Event name (e.g. `'match_completed'`, `'page_viewed'`). */
+    readonly name: string;
+    /** Subject id (typically `ctx.request.subject.id`) — anonymous when null. */
+    readonly subjectId?: string | null;
+    /**
+     * Owning tenant. Normally you DON'T set this by hand — `useAnalytics()`
+     * stamps it from the caller's `subject.tenantId` so every event is
+     * tenant-attributable + every read is tenant-scoped (the multi-tenant
+     * isolation default). Set it explicitly only for a cross-tenant system
+     * write. `null` = no tenant (system/anonymous).
+     */
+    readonly tenantId?: string | null;
+    /** Property bag. Values must be JSON-serialisable. */
+    readonly properties: Readonly<Record<string, unknown>>;
+    /** When the event occurred. Defaults to server-now when omitted. */
+    readonly occurredAt?: Date;
+}
+
+export declare type AnalyticsFailure = AnalyticsError | AnalyticsCapabilityNotSupported;
+
+/** Metric to compute. `count` = row count, `unique` = distinct subjectId,
+ *  `sum` / `avg` = numeric aggregation on a property field. */
+export declare type AnalyticsMetric = 'count' | 'unique' | {
+    readonly sum: string;
+} | {
+    readonly avg: string;
+};
+
+/**
+ * Optional CDC-mirror capability. A sink that declares `mirror` opts in
+ * to receiving the main DataStore's reactive-table changes, so
+ * analytical queries can JOIN warehouse events against live user data
+ * (`SELECT … FROM voltro_events e JOIN users u ON …`).
+ *
+ * The framework subscribes to `DataStore.onChange` once at boot, filters
+ * to the tables the sink lists in `tables`, and routes each change here.
+ * Inserts/updates `upsert` by primary key; deletes `remove`. Every call
+ * MUST be idempotent — the same change may be re-delivered after a
+ * reconnect, and the upsert is keyed on `primaryKey` so re-applying a
+ * row is a no-op-equivalent overwrite.
+ *
+ * Idempotent is not enough on its own: re-delivery can also arrive OUT
+ * OF ORDER, so both methods additionally receive a {@link MirrorVersion}
+ * and MUST ignore a write whose version is not greater than the version
+ * already stored for that key (ClickHouse gets this from
+ * `ReplacingMergeTree(version)`; DuckDB from an `ON CONFLICT … WHERE
+ * excluded.version > version` guard).
+ */
+export declare interface AnalyticsMirrorImpl {
+    /** Reactive tables this sink mirrors. The framework only forwards
+     *  changes whose `table` is in this set. */
+    readonly tables: ReadonlyArray<string>;
+    /** Primary-key column the sink upserts/deletes by. Defaults to `'id'`
+     *  when omitted. */
+    readonly primaryKey?: string;
+    /** Apply an insert/update. Idempotent upsert keyed on `primaryKey`,
+     *  version-guarded by `write.version`. */
+    readonly upsert: (write: AnalyticsMirrorUpsert) => Effect.Effect<void, AnalyticsFailure>;
+    /** Apply a delete. Idempotent — removing an absent key is a no-op —
+     *  and version-guarded by `write.version`. */
+    readonly remove: (write: AnalyticsMirrorRemove) => Effect.Effect<void, AnalyticsFailure>;
+    /**
+     * The highest version this sink has PERSISTED for one key — `null` when
+     * the key has never been written (a tombstoned key still reports its
+     * tombstone's version; both warehouse sinks keep tombstones for exactly
+     * this reason).
+     *
+     * This is the fleet-scope seed read: a replica that joins mid-stream has
+     * no per-key history of its own, so before its first write to a key it
+     * asks the warehouse where the fleet already is and continues from
+     * there. Without it a joiner would restart the key's versions low and
+     * every write it produced would be silently rejected by the sink's own
+     * `version >` guard. Called at most once per key per process (off the
+     * commit path, inside the per-key drain worker), never per change.
+     */
+    readonly maxVersion: (input: {
+        readonly table: string;
+        readonly primaryKeyValue: unknown;
+    }) => Effect.Effect<MirrorVersion | null, AnalyticsFailure>;
+}
+
+/** One delete to apply to the mirror. */
+export declare interface AnalyticsMirrorRemove {
+    readonly table: string;
+    /** Primary-key value of the removed row. */
+    readonly primaryKeyValue: unknown;
+    /** See {@link MirrorVersion}. A delete is ordered against upserts of
+     *  the same key by exactly this number. */
+    readonly version: MirrorVersion;
+}
+
+/** One insert/update to apply to the mirror. */
+export declare interface AnalyticsMirrorUpsert {
+    readonly table: string;
+    /** Post-image of the changed row. */
+    readonly row: Readonly<Record<string, unknown>>;
+    /** See {@link MirrorVersion} — persist it, compare against it, never
+     *  replace it with a local clock reading. */
+    readonly version: MirrorVersion;
+}
+
+declare type AnalyticsOptions = ({
+    readonly provider: 'duckdb';
+    readonly path?: string;
+} & MirrorOptions) | ({
+    readonly provider: 'clickhouse';
+    readonly url: string;
+    readonly username?: string;
+    readonly password?: string;
+    readonly database?: string;
+    readonly table?: string;
+    readonly batch?: AnalyticsConnectionBatch | false;
+} & MirrorOptions) | {
+    readonly provider: 'tinybird';
+    readonly token: string;
+    readonly apiUrl?: string;
+    readonly region?: string;
+    readonly datasource?: string;
+    readonly pipes?: {
+        readonly aggregate?: string;
+        readonly timeseries?: string;
+        readonly topN?: string;
+    };
+} | {
+    readonly provider: 'posthog';
+    readonly apiKey: string;
+    readonly host?: string;
+    readonly batch?: AnalyticsConnectionBatch;
+};
+
+/**
+ * The runtime contract every analytics provider implements. Plugins
+ * build a value of this shape inside their factory function and the
+ * framework wires it under `AnalyticsSink` for handler code to consume.
+ */
+export declare interface AnalyticsSinkImpl {
+    readonly info: AnalyticsSinkInfo;
+    readonly track: (event: AnalyticsEvent) => Effect.Effect<void, AnalyticsFailure>;
+    readonly aggregate: (query: AggregateQuery) => Effect.Effect<number, AnalyticsFailure>;
+    readonly timeseries: (query: TimeseriesQuery) => Effect.Effect<ReadonlyArray<AnalyticsBucket>, AnalyticsFailure>;
+    readonly topN: (query: TopNQuery) => Effect.Effect<ReadonlyArray<AnalyticsTopEntry>, AnalyticsFailure>;
+    /**
+     * Present when the sink mirrors reactive tables (opt-in via the
+     * plugin's `mirrorTables` config). Absent → no mirroring; the
+     * framework skips wiring `DataStore.onChange` for this sink.
+     */
+    readonly mirror?: AnalyticsMirrorImpl;
+}
+
+/**
+ * Per-sink metadata surfaced via the manifest endpoint + dashboard.
+ * Lets the operator see at a glance which provider is wired + what
+ * it supports without grepping app.config.ts.
+ */
+export declare interface AnalyticsSinkInfo {
+    readonly provider: string;
+    readonly capabilities: {
+        readonly track: boolean;
+        readonly aggregate: boolean;
+        readonly timeseries: boolean;
+        readonly topN: boolean;
+        /** True when the sink mirrors reactive tables into the warehouse so
+         *  analytical queries can JOIN events against live user data. */
+        readonly mirror: boolean;
+    };
+    /** Optional plugin-supplied detail (`{ ingestBufferDepth: 42 }`,
+     *  `{ url: 'https://eu.posthog.com' }`, etc.) — surfaced verbatim. */
+    readonly detail?: Readonly<Record<string, unknown>>;
+}
+
+export declare interface AnalyticsTopEntry {
+    readonly key: string;
+    readonly value: number;
+}
+
+declare interface ConnectionMetadata {
+    readonly tls?: 'auto' | 'required';
+    readonly persistence?: 'required' | 'optional' | 'none';
+    readonly keyPrefix?: string;
+    /** Explicit opt-in when a production connection intentionally uses a shared namespace. */
+    readonly allowSharedNamespace?: boolean;
+    readonly region?: string;
+    readonly label?: string;
+    readonly acl?: string;
+}
+
+declare class KvError extends KvError_base {
+    get message(): string;
+}
+
+declare const KvError_base: Schema.Class<KvError, Schema.TaggedStruct<"KvError", {
+    /** Which op failed: 'get' | 'set' | 'delete' | 'has' | 'clear' |
+     *  'list' | 'connect' | 'serialize' | 'deserialize'. */
+    readonly operation: Schema.String;
+    /** The key (or connection name) involved; '' where not applicable. */
+    readonly key: Schema.String;
+    /** `String(originalError)` — round-trip-safe diagnostic form. */
+    readonly cause: Schema.String;
+}>, YieldableError>;
+
+declare interface MirrorOptions {
+    readonly mirrorTables?: ReadonlyArray<string>;
+    readonly mirrorPrimaryKey?: string;
+}
+
+/**
+ * Ordering token for one mirrored write.
+ *
+ * **The sink MUST persist this and MUST NOT invent its own.** It is
+ * assigned by the framework at the moment the change leaves the store's
+ * change channel — i.e. in COMMIT order — so a write with a lower
+ * version is, by construction, an older image of that row. Stamping a
+ * version at sink-call time instead (a `Date.now()` inside `upsert`)
+ * makes a late-arriving STALE image outrank the fresh one and win
+ * permanently; that is the bug this type exists to make unrepresentable.
+ *
+ * How the number is derived depends on the store's `changeScope`:
+ *
+ *   - `'local'` (one process observes each change): a hybrid clock —
+ *     wall-clock microseconds forced strictly upward, so it orders within
+ *     a millisecond and keeps increasing across a restart.
+ *   - `'fleet'` (every replica observes every change): derived from the
+ *     CHANGE, not from the receiving process — the warehouse's own max
+ *     version for the key (read once via {@link AnalyticsMirrorImpl.maxVersion})
+ *     plus the change's per-key position in the totally-ordered fleet
+ *     stream. N replicas mirroring the same change therefore stamp the
+ *     SAME number, and the sink's version guard dedupes the N duplicate
+ *     writes for free — no leader, no clock, no skew hazard.
+ */
+export declare type MirrorVersion = number;
+
+/** Exact-match property filter. Values are AND'd. */
+export declare type PropertyFilter = Readonly<Record<string, string | number | boolean | null>>;
+
+export declare type TimeBucket = 'minute' | 'hour' | 'day' | 'week' | 'month';
+
+/** Time window. `to` defaults to now. */
+export declare interface TimeRange {
+    readonly from: Date;
+    readonly to?: Date;
+}
+
+export declare interface TimeseriesQuery extends AggregateQuery {
+    readonly bucket: TimeBucket;
+}
+
+export declare interface TopNQuery {
+    readonly event: string;
+    /** Property to group by (must be a string-valued property). */
+    readonly groupBy: string;
+    readonly metric: 'count' | {
+        readonly sum: string;
+    };
+    readonly n: number;
+    readonly range: TimeRange;
+    readonly filter?: PropertyFilter;
+    /** Tenant scope — injected by `useAnalytics()`; see {@link AggregateQuery.tenantId}. */
+    readonly tenantId?: string | null;
+}
+
+export { }

package/dist/analytics.js

@@ -0,0 +1,16 @@
+import { Schema as e } from "effect";
+//#region src/connectionAnalytics.ts
+var t = class extends e.TaggedError()("AnalyticsError", {
+	provider: e.String,
+	operation: e.String,
+	cause: e.String
+}) {
+	get message() {
+		return this.cause;
+	}
+}, n = class extends e.TaggedError()("AnalyticsCapabilityNotSupported", {
+	provider: e.String,
+	capability: e.String
+}) {};
+//#endregion
+export { n as AnalyticsCapabilityNotSupported, t as AnalyticsError };

package/dist/cacheAtomicProtocol.js

@@ -0,0 +1,247 @@
+//#region src/cacheAtomicProtocol.ts
+var e = class extends Error {
+	constructor() {
+		super("Invalid atomic cache command or state."), this.name = "CacheAtomicProtocolError";
+	}
+}, t = 9e5, n = () => {
+	throw new e();
+}, r = (e, t) => {
+	if (typeof e != "object" || !e || Array.isArray(e) || Object.getPrototypeOf(e) !== Object.prototype && Object.getPrototypeOf(e) !== null) return n();
+	let r = e;
+	return Object.keys(r).length !== t.length || t.some((e) => !Object.hasOwn(r, e)) ? n() : r;
+}, i = (e) => typeof e == "string" ? e : n(), a = (e) => {
+	let t = i(e);
+	return /^(?:[a-f0-9]{2})+$/.test(t) ? t : n();
+}, o = (e) => {
+	let t = i(e);
+	return /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(t) ? t : n();
+}, s = (e, t, r) => {
+	if (!Array.isArray(e)) return n();
+	let i = e.map(t);
+	return i.some((e, t) => t > 0 && r(i[t - 1]) >= r(e)) ? n() : i;
+}, c = (e) => s(e, a, (e) => e), l = (e) => Array.isArray(e) ? e : typeof e == "object" && e && Object.keys(e).length === 0 && (Object.getPrototypeOf(e) === Object.prototype || Object.getPrototypeOf(e) === null) ? [] : n(), u = (e) => {
+	if (e === null) return null;
+	let t = r(e, ["version", "tags"]);
+	return {
+		version: o(t.version),
+		tags: c(l(t.tags))
+	};
+}, d = (e) => {
+	let t = i(e);
+	return t[36] === ":" ? {
+		version: o(t.slice(0, 36)),
+		key: a(t.slice(37))
+	} : n();
+}, f = (e) => typeof e == "string" ? Array.from(new TextEncoder().encode(JSON.stringify(e)), (e) => e.toString(16).padStart(2, "0")).join("") : n(), p = (e) => `{voltro:cache:atomic:${f(e)}}:r`, m = (e) => {
+	if (typeof e != "object" || !e || Array.isArray(e)) return n();
+	let t = e.op;
+	switch (t) {
+		case "revision": return r(e, ["op"]), { op: t };
+		case "fence": return r(e, ["op"]), { op: t };
+		case "inspect": return {
+			op: t,
+			key: a(r(e, ["op", "key"]).key)
+		};
+		case "inspect-values": return {
+			op: t,
+			keys: c(r(e, ["op", "keys"]).keys)
+		};
+		case "read": {
+			let n = r(e, [
+				"op",
+				"key",
+				"snapshot"
+			]), i = u(n.snapshot);
+			return {
+				op: t,
+				key: a(n.key),
+				snapshot: i
+			};
+		}
+		case "tag": return {
+			op: t,
+			tag: a(r(e, ["op", "tag"]).tag)
+		};
+		case "scan": {
+			let a = i(r(e, ["op", "cursor"]).cursor);
+			return !/^(0|[1-9][0-9]{0,19})$/.test(a) || BigInt(a) > 18446744073709551615n ? n() : {
+				op: t,
+				cursor: a
+			};
+		}
+		case "write": {
+			let s = r(e, [
+				"op",
+				"key",
+				"snapshot",
+				"version",
+				"revision",
+				"tags",
+				"value",
+				"ttlMs",
+				"fence"
+			]), l = u(s.snapshot), d = o(s.version);
+			if (d === l?.version) return n();
+			let f = s.ttlMs;
+			if (f !== null && (typeof f != "number" || !Number.isSafeInteger(f) || f < 0)) return n();
+			let p = s.fence;
+			return p !== null && (typeof p != "number" || !Number.isSafeInteger(p) || p < 0) ? n() : {
+				op: t,
+				key: a(s.key),
+				snapshot: l,
+				version: d,
+				revision: o(s.revision),
+				tags: c(s.tags),
+				value: i(s.value),
+				ttlMs: f,
+				fence: p
+			};
+		}
+		case "remove": {
+			let n = r(e, [
+				"op",
+				"key",
+				"snapshot",
+				"revision"
+			]);
+			return {
+				op: t,
+				key: a(n.key),
+				snapshot: u(n.snapshot),
+				revision: o(n.revision)
+			};
+		}
+		case "invalidate": {
+			let c = r(e, [
+				"op",
+				"tag",
+				"members",
+				"snapshots",
+				"revision"
+			]), l = s(c.members, (e) => (d(e), i(e)), (e) => e), f = s(c.snapshots, (e) => {
+				let t = r(e, ["key", "snapshot"]);
+				return {
+					key: a(t.key),
+					snapshot: u(t.snapshot)
+				};
+			}, (e) => e.key), p = [...new Set(l.map((e) => d(e).key))].sort();
+			return p.length !== f.length || p.some((e, t) => f[t].key !== e) ? n() : {
+				op: t,
+				tag: a(c.tag),
+				members: l,
+				snapshots: f,
+				revision: o(c.revision)
+			};
+		}
+		case "clear": {
+			let n = r(e, [
+				"op",
+				"keys",
+				"revision"
+			]);
+			return {
+				op: t,
+				keys: s(n.keys, i, (e) => e),
+				revision: n.revision === null ? null : o(n.revision)
+			};
+		}
+		default: return n();
+	}
+}, h = (e, t) => {
+	if (typeof e != "string" || !/\{voltro:cache:atomic:(?:[a-f0-9]{2})+\}:r$/.test(e)) return n();
+	let r = e.slice(0, -2), i = /* @__PURE__ */ new Set(), o = (e) => {
+		i.add(`${r}:v:${a(e)}`);
+	}, s = (e) => {
+		i.add(`${r}:t:${a(e)}`);
+	}, c = () => {
+		i.add(`${r}:s`);
+	}, l = (e) => {
+		i.add(`${r}:e:${a(e)}`);
+	};
+	switch (t.op) {
+		case "inspect":
+			o(t.key);
+			break;
+		case "inspect-values":
+			t.keys.forEach(o);
+			break;
+		case "read":
+			o(t.key), t.snapshot?.tags.forEach(s);
+			break;
+		case "fence":
+			c();
+			break;
+		case "write":
+			o(t.key), t.tags.forEach(s), t.snapshot?.tags.forEach(s), t.fence !== null && t.tags.forEach(l);
+			break;
+		case "remove":
+			o(t.key), t.snapshot?.tags.forEach(s);
+			break;
+		case "tag":
+			s(t.tag);
+			break;
+		case "invalidate":
+			s(t.tag), c(), l(t.tag), t.snapshots.forEach((e) => {
+				o(e.key), e.snapshot?.tags.forEach(s);
+			});
+			break;
+		case "clear": for (let o of t.keys) if (o !== e) {
+			if (!o.startsWith(`${r}:v:`) && !o.startsWith(`${r}:t:`)) return n();
+			a(o.slice(r.length + 3)), i.add(o);
+		}
+	}
+	return [e, ...[...i].sort()];
+}, g = (e, t) => `${o(t)}:${a(e)}`, _ = (e) => e === void 0 ? null : !Number.isFinite(e) || !Number.isSafeInteger(Math.ceil(e)) ? n() : Math.max(0, Math.ceil(e)), v = (e) => {
+	if (typeof e != "object" || !e || Array.isArray(e) || Object.getPrototypeOf(e) !== Object.prototype && Object.getPrototypeOf(e) !== null) return n();
+	let t = e;
+	if (Object.keys(t).some((e) => e !== "maxTagMembers" && e !== "maxReplyBytes")) return n();
+	for (let [e, r] of Object.entries(t)) if (typeof r != "number" || !Number.isSafeInteger(r) || r < (e === "maxReplyBytes" ? 128 : 1)) return n();
+	return {
+		...Object.hasOwn(t, "maxTagMembers") ? { maxTagMembers: t.maxTagMembers } : {},
+		...Object.hasOwn(t, "maxReplyBytes") ? { maxReplyBytes: t.maxReplyBytes } : {}
+	};
+}, y = (e) => {
+	if (typeof e != "string") return n();
+	let t;
+	try {
+		t = JSON.parse(e);
+	} catch {
+		return n();
+	}
+	let i = r(t, ["status", "value"]), a = i.status;
+	return a !== "ok" && a !== "conflict" && a !== "limit" || a !== "ok" && i.value !== null ? n() : {
+		status: a,
+		value: i.value
+	};
+}, b = (e) => s(l(e), (e) => {
+	let t = r(e, ["key", "snapshot"]);
+	return {
+		key: a(t.key),
+		snapshot: u(t.snapshot)
+	};
+}, (e) => e.key), x = (e, t) => {
+	let n = r(t, ["cursor", "keys"]), a = i(n.cursor);
+	m({
+		op: "scan",
+		cursor: a
+	});
+	let o = e.slice(0, -2), s = l(n.keys).map((e) => `${o}${i(e)}`).filter((e) => e !== `${o}:s` && !e.startsWith(`${o}:e:`));
+	return h(e, {
+		op: "clear",
+		keys: [...new Set(s)].sort(),
+		revision: null
+	}), {
+		cursor: a,
+		keys: s
+	};
+}, S = (e) => [
+	"revision",
+	"fence",
+	"inspect",
+	"inspect-values",
+	"read",
+	"tag",
+	"scan"
+].includes(e.op);
+//#endregion
+export { t as CACHE_FENCE_RETENTION_MS, e as CacheAtomicProtocolError, l as cacheAtomicArray, f as cacheAtomicComponent, h as cacheAtomicKeys, d as cacheAtomicMember, g as cacheAtomicMembership, p as cacheAtomicRoot, x as cacheAtomicScanPage, u as cacheAtomicSnapshot, _ as cacheAtomicTtl, b as cacheAtomicValueSnapshots, m as decodeCacheAtomicCommand, v as decodeCacheAtomicPolicy, y as decodeCacheAtomicReply, S as isCacheAtomicRead };