@x12i/memorix-service 3.9.2 → 3.10.0

package/dist/analytics/tracker.js

@@ -0,0 +1,1302 @@
+import { ServiceError } from "../errors.js";
+import { abstractTypesOf, definitionHash, usesDatasource, validateCounterDefinition, } from "./definition.js";
+import { countexScope } from "./engine.js";
+import { buildEnvelope, hasScopePlaceholder, resolveRecordIds, scopeValuesOf, summarizePair, topLeaderIds, } from "./materializer.js";
+import { diffFacts, metricKey, projectSubject, SEP, transitionFacts, } from "./projector.js";
+/** Datasource service stamped on materialized records; writes carrying it are not counted. */
+export const ANALYTICS_DATASOURCE_SERVICE = "memorix-analytics";
+/** Built-in organization-wide census of current heads by data source. */
+export const DATASOURCES_COUNTER_ID = "@datasources";
+const UNATTRIBUTED = { system: "unattributed", name: "Unattributed" };
+function errorCode(err) {
+    return err && typeof err === "object" && "code" in err ? String(err.code) : "";
+}
+function isGone(err) {
+    const code = errorCode(err);
+    return code === "READ_NOT_FOUND" || code === "READ_ABSTRACT_MEMBER_MISSING";
+}
+/** Attribution order: `sources[0]`, then the declared `origin`, then the writing `service`. */
+export function datasourceOfRecord(record) {
+    const ds = record?._system?._datasource;
+    if (!ds || typeof ds !== "object")
+        return null;
+    const text = (v) => (typeof v === "string" ? v.trim() : "");
+    const src = Array.isArray(ds.sources) ? ds.sources[0] : undefined;
+    const connector = text(src?.system);
+    if (connector)
+        return { system: connector, name: text(src?.name) || connector };
+    const system = text(ds.origin) || text(ds.service);
+    return system ? { system, name: system } : null;
+}
+function sameJson(a, b) {
+    return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+function sortedAgents(agentIds) {
+    return [...new Set(agentIds)].sort((a, b) => a.localeCompare(b));
+}
+export class AnalyticsTracker {
+    o;
+    orgs = new Map();
+    orgInit = new Map();
+    queue = new Map();
+    drainTimer = null;
+    chain = Promise.resolve();
+    dirty = new Map();
+    backfills = new Map();
+    inflight = new Set();
+    closed = false;
+    constructor(options) {
+        this.o = {
+            debounceMs: 1_000,
+            batchMs: 25,
+            pendingStaleMs: 120_000,
+            backfillPageSize: 200,
+            refreshMs: 15_000,
+            ...options,
+        };
+    }
+    now() {
+        return this.o.now?.() ?? new Date();
+    }
+    log(message, extra) {
+        this.o.log?.(message, extra);
+    }
+    track(p) {
+        this.inflight.add(p);
+        void p.finally(() => this.inflight.delete(p)).catch(() => undefined);
+        return p;
+    }
+    serial(fn) {
+        const run = this.chain.then(fn);
+        this.chain = run.catch(() => undefined);
+        return run;
+    }
+    // ---------------------------------------------------------------- org registry cache
+    async counters(orgId, fresh = false) {
+        await this.ensureOrg(orgId);
+        const cached = this.orgs.get(orgId);
+        if (!fresh && cached && this.now().getTime() - cached.loadedAt < this.o.refreshMs)
+            return cached.counters;
+        const counters = await this.o.stateFor(orgId).listCounters();
+        this.orgs.set(orgId, { counters, loadedAt: this.now().getTime() });
+        return counters;
+    }
+    async reload(orgId) {
+        const counters = await this.o.stateFor(orgId).listCounters();
+        this.orgs.set(orgId, { counters, loadedAt: this.now().getTime() });
+    }
+    ensureOrg(orgId) {
+        let p = this.orgInit.get(orgId);
+        if (!p) {
+            p = this.initOrg(orgId).catch((err) => {
+                this.orgInit.delete(orgId);
+                throw err;
+            });
+            this.orgInit.set(orgId, p);
+        }
+        return p;
+    }
+    async initOrg(orgId) {
+        const state = this.o.stateFor(orgId);
+        await this.recoverPending(orgId);
+        const timer = setTimeout(() => void this.track(this.recoverPending(orgId)), this.o.pendingStaleMs + 1_000);
+        timer.unref?.();
+        if (this.o.datasources !== false) {
+            const census = await state.getCounter(DATASOURCES_COUNTER_ID);
+            if (!census) {
+                const at = this.now().toISOString();
+                await state.saveCounter({
+                    id: DATASOURCES_COUNTER_ID,
+                    orgId,
+                    origin: "builtin",
+                    agentIds: [],
+                    definition: {
+                        id: DATASOURCES_COUNTER_ID,
+                        name: "Data sources",
+                        target: { objectType: "", contentType: "", recordId: "" },
+                    },
+                    hash: "builtin-1",
+                    generation: 1,
+                    status: "backfilling",
+                    backfill: {},
+                    registeredAt: at,
+                    updatedAt: at,
+                });
+            }
+        }
+        const counters = await state.listCounters();
+        this.orgs.set(orgId, { counters, loadedAt: this.now().getTime() });
+        for (const c of counters) {
+            if (c.status === "backfilling")
+                this.startBackfill(orgId, c.id);
+        }
+    }
+    async recoverPending(orgId) {
+        if (this.closed)
+            return;
+        const state = this.o.stateFor(orgId);
+        const stale = await state.stalePending(new Date(this.now().getTime() - this.o.pendingStaleMs));
+        for (const id of stale) {
+            this.log("analytics: rebuilding counter left pending by an interrupted flush", { orgId, counterId: id });
+            await this.rebuildInternal(orgId, id).catch((err) => this.log("analytics: recovery rebuild failed", { orgId, counterId: id, error: String(err) }));
+        }
+    }
+    // ---------------------------------------------------------------- write hook
+    /** Called by the writer decorator after every successful write or remove. */
+    onWrite(scope, event) {
+        if (this.closed || event.datasourceService === ANALYTICS_DATASOURCE_SERVICE)
+            return;
+        void this.track(this.fanOut(scope, event).catch((err) => this.log("analytics: write fan-out failed", { orgId: scope.orgId, error: String(err) })));
+    }
+    async fanOut(scope, event) {
+        const counters = await this.counters(scope.orgId);
+        for (const c of counters) {
+            if (c.status === "error")
+                continue;
+            if (c.origin === "builtin") {
+                if (c.id === DATASOURCES_COUNTER_ID) {
+                    this.enqueue({
+                        kind: "head",
+                        orgId: scope.orgId,
+                        agentIds: scope.agentIds,
+                        objectType: event.objectType,
+                        contentType: event.contentType,
+                        recordId: event.recordId,
+                        attempts: 0,
+                    });
+                }
+                continue;
+            }
+            const def = c.definition;
+            if (def.target.objectType === event.objectType && def.target.contentType === event.contentType)
+                continue;
+            const view = this.o.metadataFor(c.agentIds);
+            for (const abstractType of abstractTypesOf(def)) {
+                if (!view.members(abstractType).some((m) => m.objectType === event.objectType))
+                    continue;
+                this.enqueue({
+                    kind: "abstract",
+                    orgId: scope.orgId,
+                    counterId: c.id,
+                    abstractType,
+                    recordId: event.recordId,
+                    attempts: 0,
+                });
+            }
+        }
+    }
+    taskKey(t) {
+        return t.kind === "abstract"
+            ? `a${SEP}${t.orgId}${SEP}${t.counterId}${SEP}${t.abstractType}${SEP}${t.recordId}`
+            : `h${SEP}${t.orgId}${SEP}${t.objectType}${SEP}${t.contentType}${SEP}${t.recordId}`;
+    }
+    enqueue(task, delayMs) {
+        if (this.closed)
+            return;
+        const key = this.taskKey(task);
+        if (!this.queue.has(key))
+            this.queue.set(key, task);
+        this.scheduleDrain(delayMs ?? this.o.batchMs);
+    }
+    scheduleDrain(delayMs) {
+        if (this.drainTimer)
+            return;
+        this.drainTimer = setTimeout(() => {
+            this.drainTimer = null;
+            void this.track(this.serial(() => this.drain()));
+        }, delayMs);
+        this.drainTimer.unref?.();
+    }
+    async drain() {
+        while (this.queue.size > 0 && !this.closed) {
+            const batch = [...this.queue.entries()].slice(0, 500);
+            for (const [k] of batch)
+                this.queue.delete(k);
+            const groups = new Map();
+            for (const [, t] of batch) {
+                const g = t.kind === "abstract" ? `${t.orgId}${SEP}${t.counterId}` : `${t.orgId}${SEP}${DATASOURCES_COUNTER_ID}`;
+                const list = groups.get(g);
+                if (list)
+                    list.push(t);
+                else
+                    groups.set(g, [t]);
+            }
+            for (const tasks of groups.values()) {
+                try {
+                    if (tasks[0].kind === "abstract")
+                        await this.processAbstract(tasks);
+                    else
+                        await this.processHeads(tasks);
+                }
+                catch (err) {
+                    this.log("analytics: reconcile failed; retrying", { error: String(err) });
+                    for (const t of tasks)
+                        this.retry(t);
+                }
+            }
+        }
+    }
+    retry(task) {
+        const attempts = task.attempts + 1;
+        if (attempts > 5) {
+            this.log("analytics: dropping task after retries", { task: this.taskKey(task) });
+            return;
+        }
+        const delay = Math.min(30_000, 250 * 2 ** attempts);
+        const timer = setTimeout(() => this.enqueue({ ...task, attempts }), delay);
+        timer.unref?.();
+    }
+    // ---------------------------------------------------------------- reconcile primitive
+    async applyEntries(orgId, counter, entries) {
+        if (entries.length === 0)
+            return;
+        const state = this.o.stateFor(orgId);
+        const gen = counter.generation;
+        const nowIso = this.now().toISOString();
+        const ledger = await state.readLedger(counter.id, gen, [...new Set(entries.map((e) => e.key))]);
+        const intents = [];
+        const incsByKey = new Map();
+        const retries = new Map();
+        const pairs = new Map();
+        const touched = new Set();
+        let rebuild = false;
+        for (const e of entries) {
+            const row = ledger.get(e.key);
+            if (incsByKey.has(e.key))
+                continue;
+            if (row?.pending) {
+                const age = Date.parse(row.pendingAt ?? nowIso);
+                if (this.now().getTime() - age >= this.o.pendingStaleMs)
+                    rebuild = true;
+                else {
+                    const timer = setTimeout(() => e.retry(), 1_000);
+                    timer.unref?.();
+                }
+                continue;
+            }
+            const prev = row
+                ? { scope: row.scope, at: row.at, facts: row.facts, track: row.track }
+                : null;
+            const { state: next, once, pair } = e.next(prev);
+            if (!prev && !next)
+                continue;
+            const incs = [];
+            const push = (s, facts, delta, at = s.at) => {
+                for (const f of facts) {
+                    incs.push({
+                        scope: s.scope,
+                        at,
+                        metric: f.metric,
+                        subject: f.subject,
+                        ...(f.split !== undefined ? { split: f.split } : {}),
+                        ...(f.value !== undefined ? { value: f.value } : {}),
+                        delta,
+                    });
+                }
+            };
+            if (prev && next && prev.scope === next.scope && prev.at === next.at) {
+                const { removed, added } = diffFacts(prev.facts, next.facts);
+                push(prev, removed, -1);
+                push(next, added, 1);
+            }
+            else {
+                if (prev)
+                    push(prev, prev.facts, -1);
+                if (next)
+                    push(next, next.facts, 1);
+            }
+            if (next && once?.length)
+                push(next, once, 1, nowIso);
+            const moved = prev?.scope !== next?.scope || prev?.at !== next?.at;
+            if (incs.length === 0 && !moved && sameJson(prev?.track, next?.track))
+                continue;
+            intents.push({ key: e.key, expectedSeq: row ? row.seq : null, next });
+            incsByKey.set(e.key, incs);
+            retries.set(e.key, e.retry);
+            if (prev)
+                touched.add(prev.scope);
+            if (next) {
+                touched.add(next.scope);
+                const known = pairs.get(next.scope);
+                if (!known || next.at < known.firstSeenAt) {
+                    pairs.set(next.scope, {
+                        scope: next.scope,
+                        counterId: counter.id,
+                        generation: gen,
+                        pair: pair ?? null,
+                        firstSeenAt: next.at,
+                    });
+                }
+            }
+        }
+        if (rebuild) {
+            await this.rebuildInternal(orgId, counter.id);
+            return;
+        }
+        if (intents.length === 0)
+            return;
+        const conflicts = new Set(await state.writeIntents(counter.id, gen, intents, nowIso));
+        const ok = intents.filter((i) => !conflicts.has(i.key)).map((i) => i.key);
+        for (const key of conflicts)
+            retries.get(key)?.();
+        const increments = ok.flatMap((k) => incsByKey.get(k) ?? []);
+        await this.o.engine.ingest(increments);
+        await this.o.engine.flush();
+        await state.commitIntents(counter.id, gen, ok);
+        for (const p of pairs.values())
+            await state.touchPair(p);
+        if (counter.origin !== "builtin")
+            this.markDirty(orgId, counter.id, touched);
+    }
+    subjectEntry(orgId, counter, abstractType, recordId, subject, retry) {
+        const def = counter.definition;
+        return {
+            key: `${abstractType}${SEP}${recordId}`,
+            retry,
+            next: (prev) => {
+                if (!subject)
+                    return { state: null };
+                const proj = projectSubject(def, abstractType, subject);
+                if (!proj.inScope)
+                    return { state: null };
+                const scope = countexScope({ orgId, counterId: counter.id, generation: counter.generation, pair: proj.pair });
+                const at = proj.clock ?? (prev && prev.scope === scope ? prev.at : this.now().toISOString());
+                return {
+                    state: { scope, at, facts: proj.facts, track: proj.track },
+                    once: prev ? transitionFacts(def, prev.track, proj.track) : [],
+                    pair: proj.pair,
+                };
+            },
+        };
+    }
+    async loadSubject(reader, scope, def, abstractType, recordId) {
+        let item;
+        try {
+            item = (await reader.getAbstract(scope, { abstractType, recordId }));
+        }
+        catch (err) {
+            if (isGone(err))
+                return null;
+            throw err;
+        }
+        return this.toSubject(reader, scope, def, item);
+    }
+    async toSubject(reader, scope, def, item) {
+        let datasource = null;
+        if (usesDatasource(def)) {
+            try {
+                const record = await reader.getContent(scope, {
+                    objectType: item.objectType,
+                    contentType: item.contentType,
+                    recordId: item.recordId,
+                });
+                datasource = datasourceOfRecord(record) ?? UNATTRIBUTED;
+            }
+            catch (err) {
+                if (!isGone(err))
+                    throw err;
+            }
+        }
+        return { recordId: item.recordId, properties: item.properties ?? {}, datasource };
+    }
+    async processAbstract(tasks) {
+        const { orgId, counterId } = tasks[0];
+        const counter = await this.o.stateFor(orgId).getCounter(counterId);
+        if (!counter || counter.status === "error")
+            return;
+        const scope = { orgId, agentIds: counter.agentIds };
+        const { reader } = this.o.portsFor(scope);
+        const entries = await Promise.all(tasks.map(async (t) => {
+            const subject = await this.loadSubject(reader, scope, counter.definition, t.abstractType, t.recordId);
+            return this.subjectEntry(orgId, counter, t.abstractType, t.recordId, subject, () => this.retry(t));
+        }));
+        await this.applyEntries(orgId, counter, entries);
+    }
+    // ---------------------------------------------------------------- @datasources census
+    headEntry(orgId, counter, recordId, observations, retry) {
+        return {
+            key: `rec${SEP}${recordId}`,
+            retry,
+            next: (prev) => {
+                const track = prev?.track
+                    ? structuredClone(prev.track)
+                    : { objectType: observations[0].objectType, heads: {} };
+                for (const o of observations) {
+                    track.objectType = o.objectType;
+                    if (o.datasource === "gone" || o.datasource?.system === ANALYTICS_DATASOURCE_SERVICE) {
+                        delete track.heads[o.contentType];
+                    }
+                    else {
+                        const ds = o.datasource ?? UNATTRIBUTED;
+                        track.heads[o.contentType] = { system: ds.system, name: ds.name ?? ds.system };
+                    }
+                }
+                const contentTypes = Object.keys(track.heads).sort();
+                if (contentTypes.length === 0)
+                    return { state: null };
+                const facts = [];
+                const systems = new Set();
+                for (const ct of contentTypes) {
+                    const h = track.heads[ct];
+                    facts.push({ metric: `dh${SEP}${h.system}`, subject: track.objectType, split: ct });
+                    facts.push({ metric: `dl${SEP}${h.system}`, subject: h.name });
+                    systems.add(h.system);
+                }
+                for (const s of [...systems].sort())
+                    facts.push({ metric: `dsub${SEP}${s}`, subject: track.objectType });
+                const scope = countexScope({ orgId, counterId: counter.id, generation: counter.generation, pair: null });
+                return {
+                    state: { scope, at: prev?.at ?? this.now().toISOString(), facts, track: track },
+                };
+            },
+        };
+    }
+    async processHeads(tasks) {
+        const orgId = tasks[0].orgId;
+        const counter = await this.o.stateFor(orgId).getCounter(DATASOURCES_COUNTER_ID);
+        if (!counter || counter.status === "error")
+            return;
+        const byRecord = new Map();
+        for (const t of tasks) {
+            const scope = { orgId, agentIds: t.agentIds };
+            let datasource;
+            try {
+                const record = await this.o.portsFor(scope).reader.getContent(scope, {
+                    objectType: t.objectType,
+                    contentType: t.contentType,
+                    recordId: t.recordId,
+                });
+                datasource = datasourceOfRecord(record);
+            }
+            catch (err) {
+                if (!isGone(err))
+                    throw err;
+                datasource = "gone";
+            }
+            const e = byRecord.get(t.recordId) ?? { tasks: [], obs: [] };
+            e.tasks.push(t);
+            e.obs.push({ objectType: t.objectType, contentType: t.contentType, datasource });
+            byRecord.set(t.recordId, e);
+        }
+        const entries = [...byRecord.entries()].map(([recordId, e]) => this.headEntry(orgId, counter, recordId, e.obs, () => e.tasks.forEach((t) => this.retry(t))));
+        await this.applyEntries(orgId, counter, entries);
+    }
+    async sourceCensus(scope) {
+        const timestamp = this.now().toISOString();
+        if (this.o.datasources === false) {
+            return { ok: true, censusId: null, timestamp, status: "disabled", subjects: [], heads: [] };
+        }
+        await this.ensureOrg(scope.orgId);
+        await this.chain;
+        const counter = await this.o.stateFor(scope.orgId).getCounter(DATASOURCES_COUNTER_ID);
+        if (!counter || counter.status !== "live") {
+            return {
+                ok: true,
+                censusId: null,
+                timestamp,
+                status: counter?.status ?? "backfilling",
+                subjects: [],
+                heads: [],
+            };
+        }
+        const cells = await this.o.engine.readCells(countexScope({ orgId: scope.orgId, counterId: counter.id, generation: counter.generation, pair: null }));
+        const view = this.o.metadataFor(scope.agentIds);
+        const names = new Map();
+        const grain = (prefix) => {
+            const bySystem = new Map();
+            for (const c of cells) {
+                if (c.count <= 0 || !c.metric.startsWith(prefix))
+                    continue;
+                const system = c.metric.slice(prefix.length);
+                const kinds = bySystem.get(system) ?? new Map();
+                kinds.set(c.subject, (kinds.get(c.subject) ?? 0) + c.count);
+                bySystem.set(system, kinds);
+            }
+            return bySystem;
+        };
+        for (const c of cells) {
+            if (c.count <= 0 || !c.metric.startsWith(`dl${SEP}`))
+                continue;
+            const system = c.metric.slice(3);
+            const best = names.get(system);
+            if (!best || c.count > best.n)
+                names.set(system, { name: c.subject, n: c.count });
+        }
+        const shape = (bySystem) => [...bySystem.entries()]
+            .map(([system, kinds]) => {
+            const list = [...kinds.entries()]
+                .map(([kind, count]) => ({ kind, label: view.objectTypeName(kind) ?? kind, count }))
+                .sort((a, b) => b.count - a.count || a.kind.localeCompare(b.kind));
+            return {
+                system,
+                name: names.get(system)?.name ?? system,
+                total: list.reduce((n, k) => n + k.count, 0),
+                kinds: list,
+            };
+        })
+            .sort((a, b) => b.total - a.total || a.system.localeCompare(b.system));
+        return {
+            ok: true,
+            censusId: `${DATASOURCES_COUNTER_ID}#${counter.generation}`,
+            timestamp: counter.liveAt ?? timestamp,
+            status: "live",
+            subjects: shape(grain(`dsub${SEP}`)),
+            heads: shape(grain(`dh${SEP}`)),
+        };
+    }
+    // ---------------------------------------------------------------- registry
+    /** Registers (or updates) the analytics[] items of the scope's installed packs. */
+    async syncPack(scope) {
+        if (this.closed)
+            return;
+        const agentIds = sortedAgents(scope.agentIds);
+        const view = this.o.metadataFor(agentIds);
+        const counters = await this.counters(scope.orgId, true);
+        const seen = new Set();
+        for (const raw of view.analytics()) {
+            const id = raw && typeof raw === "object" ? String(raw.id ?? "") : "";
+            if (!id)
+                continue;
+            seen.add(id);
+            const existing = counters.find((c) => c.id === id);
+            if (existing && existing.origin !== "pack")
+                continue;
+            const hash = definitionHash(raw);
+            if (existing && existing.hash === hash && existing.status !== "error")
+                continue;
+            try {
+                await this.register(scope, raw, { origin: "pack", replace: true });
+            }
+            catch (err) {
+                this.log("analytics: pack counter rejected", { orgId: scope.orgId, id, error: String(err) });
+                const at = this.now().toISOString();
+                const issues = err instanceof ServiceError ? err.details : undefined;
+                if (!existing) {
+                    await this.o.stateFor(scope.orgId).saveCounter({
+                        id,
+                        orgId: scope.orgId,
+                        origin: "pack",
+                        agentIds,
+                        definition: raw,
+                        hash,
+                        generation: 1,
+                        status: "error",
+                        backfill: {},
+                        registeredAt: at,
+                        updatedAt: at,
+                        error: `${err instanceof Error ? err.message : String(err)}${issues ? ` ${JSON.stringify(issues)}` : ""}`,
+                    });
+                }
+            }
+        }
+        for (const c of counters) {
+            if (c.origin === "pack" && !seen.has(c.id) && sameJson(sortedAgents(c.agentIds), agentIds)) {
+                await this.unregister(scope.orgId, c.id, { allowPack: true });
+            }
+        }
+        await this.reload(scope.orgId);
+    }
+    validate(scope, raw) {
+        return validateCounterDefinition(raw, this.o.metadataFor(sortedAgents(scope.agentIds)).catalog);
+    }
+    async register(scope, raw, opts) {
+        const agentIds = sortedAgents(scope.agentIds);
+        const issues = this.validate(scope, raw);
+        if (issues.length > 0) {
+            throw new ServiceError("ANALYTICS_DEFINITION_INVALID", "analytics definition is invalid", 400, { issues });
+        }
+        const def = raw;
+        if (def.id.startsWith("@")) {
+            throw new ServiceError("ANALYTICS_DEFINITION_INVALID", "counter ids starting with @ are reserved", 400);
+        }
+        const state = this.o.stateFor(scope.orgId);
+        const counters = await this.counters(scope.orgId, true);
+        const existing = counters.find((c) => c.id === def.id) ?? null;
+        const hash = definitionHash(def);
+        if (existing) {
+            if (existing.origin !== opts.origin) {
+                throw new ServiceError("ANALYTICS_COUNTER_CONFLICT", `counter "${def.id}" is registered by ${existing.origin}; pick another id`, 409);
+            }
+            if (existing.hash === hash && sameJson(existing.agentIds, agentIds) && existing.status !== "error") {
+                return existing;
+            }
+            if (!opts.replace) {
+                throw new ServiceError("ANALYTICS_COUNTER_EXISTS", `counter "${def.id}" exists with a different definition; pass replace: true to rebuild it`, 409);
+            }
+        }
+        const clash = counters.find((c) => c.id !== def.id &&
+            c.origin !== "builtin" &&
+            c.definition.target.objectType === def.target.objectType &&
+            c.definition.target.contentType === def.target.contentType &&
+            c.definition.target.recordId === def.target.recordId);
+        if (clash) {
+            throw new ServiceError("ANALYTICS_TARGET_CONFLICT", `counter "${clash.id}" already materializes into this target`, 409);
+        }
+        const at = this.now().toISOString();
+        const record = {
+            id: def.id,
+            orgId: scope.orgId,
+            origin: opts.origin,
+            agentIds,
+            definition: def,
+            hash,
+            generation: (existing?.generation ?? 0) + 1,
+            status: "backfilling",
+            backfill: {},
+            registeredAt: existing?.registeredAt ?? at,
+            updatedAt: at,
+            registeredBy: opts.registeredBy ?? existing?.registeredBy ?? null,
+            liveAt: null,
+            lastMaterializedAt: existing?.lastMaterializedAt ?? null,
+            error: null,
+        };
+        await state.saveCounter(record);
+        if (existing)
+            await this.dropGeneration(scope.orgId, existing);
+        await this.reload(scope.orgId);
+        this.writePlaceholder(record);
+        this.startBackfill(scope.orgId, record.id);
+        return record;
+    }
+    async unregister(orgId, id, opts = {}) {
+        const state = this.o.stateFor(orgId);
+        const existing = await state.getCounter(id);
+        if (!existing)
+            return false;
+        if (existing.origin === "builtin" || (existing.origin === "pack" && !opts.allowPack)) {
+            throw new ServiceError("ANALYTICS_COUNTER_NOT_REMOVABLE", existing.origin === "pack"
+                ? `counter "${id}" comes from an installed pack; remove it from the pack's analytics[]`
+                : `counter "${id}" is built in`, 409);
+        }
+        await state.deleteCounter(id);
+        await state.dropGenerations(id);
+        await this.o.dropCells?.(orgId, `${encodeURIComponent(orgId)}|${encodeURIComponent(id)}#`);
+        const d = this.dirty.get(`${orgId}${SEP}${id}`);
+        if (d) {
+            clearTimeout(d.timer);
+            this.dirty.delete(`${orgId}${SEP}${id}`);
+        }
+        await this.reload(orgId);
+        return true;
+    }
+    /**
+     * Data-source stamps changed outside the writer (datasource backfill): rebuild the counters
+     * that count by `@datasource`, including the built-in census. Returns their ids.
+     */
+    async datasourcesRestamped(orgId) {
+        const rebuilt = [];
+        for (const c of await this.counters(orgId, true)) {
+            const depends = c.origin === "builtin" ? c.id === DATASOURCES_COUNTER_ID : usesDatasource(c.definition);
+            if (!depends)
+                continue;
+            await this.rebuildInternal(orgId, c.id);
+            rebuilt.push(c.id);
+        }
+        return rebuilt;
+    }
+    async rebuild(orgId, id) {
+        await this.ensureOrg(orgId);
+        const rec = await this.rebuildInternal(orgId, id);
+        if (!rec)
+            throw new ServiceError("ANALYTICS_COUNTER_NOT_FOUND", `counter "${id}" not found`, 404);
+        return rec;
+    }
+    async rebuildInternal(orgId, id) {
+        const state = this.o.stateFor(orgId);
+        const existing = await state.getCounter(id);
+        if (!existing)
+            return null;
+        const next = {
+            ...existing,
+            generation: existing.generation + 1,
+            status: "backfilling",
+            backfill: {},
+            liveAt: null,
+            error: null,
+            updatedAt: this.now().toISOString(),
+        };
+        await state.saveCounter(next);
+        await this.dropGeneration(orgId, existing);
+        await this.reload(orgId);
+        this.writePlaceholder(next);
+        this.startBackfill(orgId, id);
+        return next;
+    }
+    async dropGeneration(orgId, old) {
+        const state = this.o.stateFor(orgId);
+        await state.dropGenerations(old.id, old.generation + 1);
+        await this.o
+            .dropCells?.(orgId, `${encodeURIComponent(orgId)}|${encodeURIComponent(old.id)}#${old.generation}|`)
+            .catch((err) => this.log("analytics: dropping old cells failed", { orgId, error: String(err) }));
+    }
+    async list(scope) {
+        return [...(await this.counters(scope.orgId, true))].sort((a, b) => a.id.localeCompare(b.id));
+    }
+    async get(scope, id) {
+        await this.ensureOrg(scope.orgId);
+        return this.o.stateFor(scope.orgId).getCounter(id);
+    }
+    // ---------------------------------------------------------------- backfill
+    startBackfill(orgId, id) {
+        const key = `${orgId}${SEP}${id}`;
+        if (this.backfills.has(key) || this.closed)
+            return;
+        const state = this.o.stateFor(orgId);
+        let ranGeneration = null;
+        const run = this.runBackfill(orgId, id, (g) => (ranGeneration = g))
+            .catch(async (err) => {
+            this.log("analytics: backfill failed", { orgId, counterId: id, error: String(err) });
+            const c = await state.getCounter(id);
+            if (c) {
+                await state.patchCounter(id, { status: "error", error: err instanceof Error ? err.message : String(err), updatedAt: this.now().toISOString() }, c.generation);
+                await this.reload(orgId);
+            }
+        })
+            .then(async () => {
+            this.backfills.delete(key);
+            const c = await state.getCounter(id);
+            if (c?.status === "backfilling" && c.generation !== ranGeneration)
+                this.startBackfill(orgId, id);
+        })
+            .catch(() => {
+            this.backfills.delete(key);
+        });
+        this.backfills.set(key, run);
+        void this.track(run);
+    }
+    async runBackfill(orgId, id, started) {
+        const state = this.o.stateFor(orgId);
+        let counter = await state.getCounter(id);
+        if (!counter || counter.status !== "backfilling")
+            return;
+        const gen = counter.generation;
+        started(gen);
+        const stillCurrent = async () => {
+            const c = await state.getCounter(id);
+            return c && c.generation === gen && c.status === "backfilling" && !this.closed ? c : null;
+        };
+        const saveProgress = async (key, progress) => {
+            counter.backfill[key] = progress;
+            await state.patchCounter(id, { backfill: counter.backfill, updatedAt: this.now().toISOString() }, gen);
+        };
+        if (counter.origin === "builtin") {
+            if (!this.o.heads) {
+                this.log("analytics: no head source; @datasources counts new writes only", { orgId });
+            }
+            else {
+                for (const coll of await this.o.heads.collections(orgId)) {
+                    let progress = counter.backfill[coll.key] ?? { cursor: null, done: false, seen: 0 };
+                    while (!progress.done) {
+                        const current = await stillCurrent();
+                        if (!current)
+                            return;
+                        counter = current;
+                        const rows = await this.o.heads.page(orgId, coll.key, progress.cursor, this.o.backfillPageSize);
+                        const byRecord = new Map();
+                        for (const r of rows) {
+                            const list = byRecord.get(r.recordId) ?? [];
+                            list.push({ objectType: coll.objectType, contentType: coll.contentType, datasource: r.datasource });
+                            byRecord.set(r.recordId, list);
+                        }
+                        const c = counter;
+                        await this.serial(() => this.applyEntries(orgId, c, [...byRecord.entries()].map(([rid, obs]) => this.headEntry(orgId, c, rid, obs, () => undefined))));
+                        progress = {
+                            cursor: rows.length ? rows[rows.length - 1].id : progress.cursor,
+                            done: rows.length < this.o.backfillPageSize,
+                            seen: progress.seen + rows.length,
+                        };
+                        await saveProgress(coll.key, progress);
+                    }
+                }
+            }
+        }
+        else {
+            const def = counter.definition;
+            const scope = { orgId, agentIds: counter.agentIds };
+            const { reader } = this.o.portsFor(scope);
+            for (const abstractType of abstractTypesOf(def)) {
+                let progress = counter.backfill[abstractType] ?? { cursor: null, done: false, seen: 0 };
+                while (!progress.done) {
+                    const current = await stillCurrent();
+                    if (!current)
+                        return;
+                    counter = current;
+                    const page = await reader.listAbstract(scope, {
+                        abstractType,
+                        limit: this.o.backfillPageSize,
+                        ...(progress.cursor ? { cursor: progress.cursor } : {}),
+                    });
+                    const c = counter;
+                    const entries = [];
+                    for (const item of page.items) {
+                        const subject = await this.toSubject(reader, scope, def, item);
+                        entries.push(this.subjectEntry(orgId, c, abstractType, item.recordId, subject, () => this.enqueue({ kind: "abstract", orgId, counterId: id, abstractType, recordId: item.recordId, attempts: 0 })));
+                    }
+                    await this.serial(() => this.applyEntries(orgId, c, entries));
+                    progress = {
+                        cursor: page.nextCursor ?? null,
+                        done: !page.nextCursor,
+                        seen: progress.seen + page.items.length,
+                    };
+                    await saveProgress(abstractType, progress);
+                }
+            }
+        }
+        const at = this.now().toISOString();
+        const promoted = await state.patchCounter(id, { status: "live", liveAt: at, updatedAt: at }, gen);
+        await this.reload(orgId);
+        if (promoted && counter.origin !== "builtin") {
+            await this.serial(() => this.materialize(orgId, id, "all", false));
+        }
+    }
+    // ---------------------------------------------------------------- materialization
+    markDirty(orgId, counterId, scopes) {
+        const key = `${orgId}${SEP}${counterId}`;
+        const d = this.dirty.get(key);
+        if (d) {
+            for (const s of scopes)
+                d.scopes.add(s);
+            return;
+        }
+        const entry = {
+            orgId,
+            counterId,
+            scopes: new Set(scopes),
+            timer: setTimeout(() => {
+                this.dirty.delete(key);
+                void this.track(this.serial(() => this.materialize(orgId, counterId, entry.scopes, false)).catch((err) => this.log("analytics: materialize failed", { orgId, counterId, error: String(err) })));
+            }, this.o.debounceMs),
+        };
+        entry.timer.unref?.();
+        this.dirty.set(key, entry);
+    }
+    /**
+     * Materializes the counter now (pipeline step). With covering-scope values, that pair's
+     * history slot is rewritten as well as the current record.
+     */
+    async materializeNow(scope, id, scopeValues) {
+        await this.ensureOrg(scope.orgId);
+        await this.chain;
+        const counter = await this.o.stateFor(scope.orgId).getCounter(id);
+        const dirty = new Set();
+        const pairDef = counter?.origin !== "builtin" ? counter?.definition.scope : undefined;
+        if (counter && pairDef && scopeValues) {
+            const a = scopeValues[pairDef[0].key];
+            const b = scopeValues[pairDef[1].key];
+            if (typeof a === "string" && a && typeof b === "string" && b) {
+                dirty.add(countexScope({ orgId: scope.orgId, counterId: id, generation: counter.generation, pair: [a, b] }));
+            }
+        }
+        return this.serial(() => this.materialize(scope.orgId, id, dirty, false));
+    }
+    /** Publishes an all-`produced: false` body while the counter backfills. Never awaited: callers may hold the chain. */
+    writePlaceholder(counter) {
+        if (counter.origin === "builtin")
+            return;
+        const def = counter.definition;
+        if (hasScopePlaceholder(def, def.target.recordId))
+            return;
+        void this.track(this.serial(() => this.materialize(counter.orgId, counter.id, new Set(), true)).catch((err) => this.log("analytics: placeholder write failed", { counterId: counter.id, error: String(err) })));
+    }
+    async materialize(orgId, id, dirtyScopes, allowNotLive) {
+        const state = this.o.stateFor(orgId);
+        const counter = await state.getCounter(id);
+        if (!counter)
+            return { materialized: false, recordId: null, historyRecordId: null, status: "missing" };
+        if (counter.origin === "builtin") {
+            return { materialized: false, recordId: null, historyRecordId: null, status: counter.status };
+        }
+        const live = counter.status === "live";
+        if (!live && !allowNotLive) {
+            return { materialized: false, recordId: null, historyRecordId: null, status: counter.status };
+        }
+        const def = counter.definition;
+        const scope = { orgId, agentIds: counter.agentIds };
+        const generatedAt = this.now().toISOString();
+        const historyLimit = def.history?.limit ?? 12;
+        const needsSeries = (def.trends ?? []).length > 0;
+        const orgWide = !def.scope;
+        let pairs;
+        if (orgWide) {
+            pairs = [
+                {
+                    scope: countexScope({ orgId, counterId: id, generation: counter.generation, pair: null }),
+                    counterId: id,
+                    generation: counter.generation,
+                    pair: null,
+                    firstSeenAt: counter.liveAt ?? generatedAt,
+                },
+            ];
+        }
+        else {
+            pairs = live ? await state.listPairs(id, counter.generation, Math.max(2, needsSeries ? historyLimit : 2)) : [];
+            if (pairs.length === 0) {
+                if (hasScopePlaceholder(def, def.target.recordId)) {
+                    return { materialized: false, recordId: null, historyRecordId: null, status: counter.status };
+                }
+                pairs = [
+                    {
+                        scope: countexScope({ orgId, counterId: id, generation: counter.generation, pair: null }),
+                        counterId: id,
+                        generation: counter.generation,
+                        pair: null,
+                        firstSeenAt: generatedAt,
+                    },
+                ];
+            }
+        }
+        const cellCache = new Map();
+        const cellsOf = (s) => {
+            let p = cellCache.get(s);
+            if (!p) {
+                p = live ? this.o.engine.readCells(s) : Promise.resolve([]);
+                cellCache.set(s, p);
+            }
+            return p;
+        };
+        const summaryCache = new Map();
+        const summaryOf = (p) => {
+            let s = summaryCache.get(p.scope);
+            if (!s) {
+                s = cellsOf(p.scope).then((cells) => summarizePair(def, cells, { live, organizationWide: orgWide }));
+                summaryCache.set(p.scope, s);
+            }
+            return s;
+        };
+        const envelopeFor = async (index) => {
+            const pairRow = pairs[index];
+            const current = await summaryOf(pairRow);
+            const previous = pairs[index + 1] ? await summaryOf(pairs[index + 1]) : null;
+            const windows = {};
+            if (live) {
+                const wanted = new Set((def.measures ?? []).flatMap((m) => m.windows ?? []));
+                for (const w of wanted)
+                    windows[w] = await this.o.engine.readWindow(pairRow.scope, w, this.now());
+            }
+            const trends = await this.trends(def, pairs.slice(index), summaryOf, live, orgWide);
+            const leaders = live ? await this.leaders(scope, def, await cellsOf(pairRow.scope), pairRow.pair) : this.emptyLeaders(def);
+            return buildEnvelope({
+                definition: def,
+                counter: {
+                    id,
+                    generation: counter.generation,
+                    status: counter.status,
+                    hash: counter.hash,
+                    origin: counter.origin,
+                },
+                generatedAt,
+                pair: pairRow.pair,
+                current,
+                previous,
+                windows,
+                trends,
+                leaders,
+            });
+        };
+        const currentEnvelope = await envelopeFor(0);
+        const ids = resolveRecordIds(def, pairs[0].pair);
+        await this.writeRecord(scope, def, ids.current, def.name, currentEnvelope);
+        let historyRecordId = null;
+        if (def.history && ids.history) {
+            historyRecordId = ids.history;
+            const targets = new Map([[ids.history, 0]]);
+            if (hasScopePlaceholder(def, def.history.recordId)) {
+                pairs.forEach((p, i) => {
+                    if (i > 0 && (dirtyScopes === "all" || dirtyScopes.has(p.scope))) {
+                        const hid = resolveRecordIds(def, p.pair).history;
+                        if (!targets.has(hid))
+                            targets.set(hid, i);
+                    }
+                });
+            }
+            for (const [recordId, index] of targets) {
+                const body = index === 0 ? currentEnvelope : await envelopeFor(index);
+                await this.writeRecord(scope, def, recordId, `${def.name} history`, {
+                    ...body,
+                    historySlot: true,
+                    coveringScope: scopeValuesOf(def, pairs[index].pair),
+                });
+            }
+        }
+        await state.patchCounter(id, { lastMaterializedAt: generatedAt }, counter.generation);
+        return { materialized: true, recordId: ids.current, historyRecordId, status: counter.status };
+    }
+    emptyLeaders(def) {
+        return Object.fromEntries((def.leaders ?? []).map((l) => [l.key, []]));
+    }
+    async leaders(scope, def, cells, pair) {
+        const out = {};
+        const { reader } = this.o.portsFor(scope);
+        const prop = (item, p) => p === "recordId" ? item.recordId : item.properties?.[p];
+        for (const l of def.leaders ?? []) {
+            const limit = l.limit ?? 10;
+            try {
+                if (l.countOf) {
+                    const top = topLeaderIds(cells, l.key, limit);
+                    const items = new Map();
+                    if (top.length > 0) {
+                        if (l.idProperty === "recordId") {
+                            const found = await Promise.all(top.map((t) => reader
+                                .getAbstract(scope, { abstractType: l.abstractType, recordId: t.id })
+                                .then((it) => it)
+                                .catch(() => null)));
+                            for (const it of found)
+                                if (it)
+                                    items.set(it.recordId, it);
+                        }
+                        else {
+                            const page = await reader
+                                .listAbstract(scope, {
+                                abstractType: l.abstractType,
+                                filters: [{ field: l.idProperty, op: "in", value: top.map((t) => t.id) }],
+                                limit: top.length,
+                            })
+                                .catch(() => ({ items: [] }));
+                            for (const it of page.items) {
+                                items.set(String(prop(it, l.idProperty)), it);
+                            }
+                        }
+                    }
+                    out[l.key] = top.map((t) => {
+                        const it = items.get(t.id);
+                        const row = { id: t.id, label: (it && prop(it, l.labelProperty)) ?? t.id, count: t.count };
+                        for (const c of l.columns ?? []) {
+                            if (c.kind === "count")
+                                row[c.key] = t.count;
+                            else if (c.property && it)
+                                row[c.key] = prop(it, c.property);
+                        }
+                        return row;
+                    });
+                }
+                else {
+                    const filters = (def.scope ?? [])
+                        .map((s, i) => ({ s, value: pair?.[i] }))
+                        .filter(({ s, value }) => s.abstractType === l.abstractType && value !== undefined)
+                        .map(({ s, value }) => ({ field: s.property, op: "eq", value }));
+                    const page = await reader.listAbstract(scope, {
+                        abstractType: l.abstractType,
+                        ...(filters.length ? { filters } : {}),
+                        sort: (l.sort ?? []).map((s) => ({ field: s.property, direction: s.direction ?? "desc" })),
+                        limit,
+                    });
+                    out[l.key] = page.items.map((it) => {
+                        const row = { id: prop(it, l.idProperty), label: prop(it, l.labelProperty) };
+                        for (const c of l.columns ?? []) {
+                            if (c.kind === "count")
+                                row[c.key] = 1;
+                            else if (c.property)
+                                row[c.key] = prop(it, c.property);
+                        }
+                        return row;
+                    });
+                }
+            }
+            catch (err) {
+                this.log("analytics: leader read failed", { leader: l.key, error: String(err) });
+                out[l.key] = [];
+            }
+        }
+        return out;
+    }
+    async trends(def, pairs, summaryOf, live, orgWide) {
+        const out = [];
+        const historyLimit = def.history?.limit ?? 12;
+        const now = this.now();
+        for (const t of def.trends ?? []) {
+            const m = (def.measures ?? []).find((x) => x.key === t.measure);
+            for (const window of t.windows) {
+                if (!live || !m) {
+                    out.push({ key: t.key, label: t.label, window, points: [] });
+                    continue;
+                }
+                if (window === "snapshots") {
+                    const points = [];
+                    for (const p of pairs.slice(0, historyLimit)) {
+                        const v = (await summaryOf(p)).measures[t.measure];
+                        if (v?.produced && typeof v.value === "number") {
+                            points.push({ at: p.firstSeenAt, scope: scopeValuesOf(def, p.pair), value: v.value });
+                        }
+                    }
+                    out.push({ key: t.key, label: t.label, window, points });
+                    continue;
+                }
+                const days = window === "7d" ? 7 : 30;
+                if (def.clock?.abstractType === m.abstractType && m.kind === "count") {
+                    const series = await this.o.engine.readDaily(pairs[0].scope, metricKey.measure(m.key), days, now);
+                    const byDay = new Map(series.map((p) => [p.at, p.value]));
+                    const points = [];
+                    for (let i = days - 1; i >= 0; i--) {
+                        const day = new Date(now.getTime() - i * 86_400_000).toISOString().slice(0, 10);
+                        points.push({ at: day, value: byDay.get(day) ?? 0 });
+                    }
+                    out.push({ key: t.key, label: t.label, window, points });
+                    continue;
+                }
+                if (orgWide) {
+                    out.push({ key: t.key, label: t.label, window, points: [] });
+                    continue;
+                }
+                const byDay = new Map();
+                for (const p of [...pairs].reverse()) {
+                    const age = (now.getTime() - Date.parse(p.firstSeenAt)) / 86_400_000;
+                    if (!(age >= 0 && age <= days))
+                        continue;
+                    const v = (await summaryOf(p)).measures[t.measure];
+                    if (v?.produced && typeof v.value === "number")
+                        byDay.set(p.firstSeenAt.slice(0, 10), v.value);
+                }
+                out.push({
+                    key: t.key,
+                    label: t.label,
+                    window,
+                    points: [...byDay.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([at, value]) => ({ at, value })),
+                });
+            }
+        }
+        return out;
+    }
+    async writeRecord(scope, def, recordId, title, data) {
+        const { reader, writer } = this.o.portsFor(scope);
+        const address = { objectType: def.target.objectType, contentType: def.target.contentType, recordId };
+        const draft = {
+            format: "memorix-record/2",
+            recordId,
+            objectType: address.objectType,
+            contentType: address.contentType,
+            dataCategory: this.o.metadataFor(scope.agentIds).dataCategoryOf(address.objectType),
+            concept: {
+                title,
+                identifiers: { primary: { kind: "recordId", value: recordId, issuer: ANALYTICS_DATASOURCE_SERVICE } },
+            },
+            data,
+        };
+        const datasource = { service: ANALYTICS_DATASOURCE_SERVICE, declared: false };
+        for (let attempt = 0;; attempt++) {
+            let revision = null;
+            try {
+                revision = (await reader.getContent(scope, address)).revision;
+            }
+            catch (err) {
+                if (!isGone(err))
+                    throw err;
+            }
+            try {
+                if (revision === null) {
+                    await writer.add({ scope, precondition: { kind: "absent" }, record: draft, datasource });
+                }
+                else {
+                    await writer.upsert({
+                        scope,
+                        precondition: { kind: "revision", revision },
+                        record: { ...draft, revision },
+                        datasource,
+                    });
+                }
+                return;
+            }
+            catch (err) {
+                const code = errorCode(err);
+                if (attempt < 3 && (code === "WRITE_NOT_ABSENT" || code === "WRITE_STALE_REVISION"))
+                    continue;
+                throw err;
+            }
+        }
+    }
+    // ---------------------------------------------------------------- lifecycle
+    /** Resolves once queued reconciles, backfills, and debounced materializations have run. */
+    async idle(timeoutMs = 60_000) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            await this.chain;
+            await Promise.allSettled([...this.inflight]);
+            await this.chain;
+            const busy = this.queue.size > 0 || this.drainTimer !== null || this.dirty.size > 0 || this.backfills.size > 0 || this.inflight.size > 0;
+            if (!busy)
+                return;
+            if (Date.now() > deadline)
+                throw new Error("analytics tracker did not settle");
+            await new Promise((r) => setTimeout(r, Math.max(5, Math.min(this.o.batchMs, this.o.debounceMs))));
+        }
+    }
+    async close() {
+        this.closed = true;
+        if (this.drainTimer)
+            clearTimeout(this.drainTimer);
+        this.drainTimer = null;
+        for (const d of this.dirty.values())
+            clearTimeout(d.timer);
+        this.dirty.clear();
+        this.queue.clear();
+        await this.chain;
+        await Promise.allSettled([...this.backfills.values()]);
+        await this.o.engine.flush().catch(() => undefined);
+    }
+}
+/** Wraps the shared content writer so every successful write reaches the tracker. */
+export function withAnalyticsTracking(writer, onWrite) {
+    const emit = (scope, objectType, contentType, recordId, datasource) => {
+        try {
+            onWrite(scope, { objectType, contentType, recordId, datasourceService: datasource?.service });
+        }
+        catch {
+            /* tracking never fails a write */
+        }
+    };
+    return {
+        async add(req) {
+            const res = await writer.add(req);
+            emit(req.scope, res.record.objectType, res.record.contentType, res.record.recordId, req.datasource);
+            return res;
+        },
+        async upsert(req) {
+            const res = await writer.upsert(req);
+            emit(req.scope, res.record.objectType, res.record.contentType, res.record.recordId, req.datasource);
+            return res;
+        },
+        async replace(req) {
+            const res = await writer.replace(req);
+            emit(req.scope, res.record.objectType, res.record.contentType, res.record.recordId, req.datasource);
+            return res;
+        },
+        async patch(req) {
+            const res = await writer.patch(req);
+            emit(req.scope, req.objectType, req.contentType, req.recordId, req.datasource);
+            return res;
+        },
+        async moveFields(req) {
+            const res = await writer.moveFields(req);
+            emit(req.scope, req.objectType, req.contentType, req.recordId, req.datasource);
+            return res;
+        },
+        async remove(req) {
+            const res = await writer.remove(req);
+            emit(req.scope, req.objectType, req.contentType, req.recordId);
+            return res;
+        },
+        reconcileDirectory(scope, recordId) {
+            return writer.reconcileDirectory(scope, recordId);
+        },
+    };
+}
+/** Abstract reverse-writes go through their own concrete writer; report them too. */
+export function withAbstractTracking(abstractWriter, onWrite) {
+    return {
+        async patchAbstract(req) {
+            const res = await abstractWriter.patchAbstract(req);
+            try {
+                onWrite(req.scope, {
+                    objectType: res.objectType,
+                    contentType: res.contentType,
+                    recordId: res.record.recordId,
+                    datasourceService: req.datasource?.service,
+                });
+            }
+            catch {
+                /* tracking never fails a write */
+            }
+            return res;
+        },
+    };
+}
+//# sourceMappingURL=tracker.js.map