@friggframework/core 2.0.0-next.11 → 2.0.0-next.110

package/types/module-plugin/index.d.ts

@@ -1,75 +1,26 @@
 declare module "@friggframework/module-plugin" {
-  import { Model } from "mongoose";
   import { Delegate, IFriggDelegate } from "@friggframework/core";
 
-  export class Credential extends Model {
-    userId: string;
-    auth_is_valid: boolean;
-    subType: string;
-    externalId: string;
+  export interface Credential {
+    id?: string;
+    userId?: string;
+    authIsValid?: boolean;
+    externalId?: string;
+    data?: any;
   }
 
-  export class EntityManager implements IFriggEntityManager {
-    static primaryEntityClass: any;
-    static entityManagerClasses: any[];
-    static entityTypes: string[];
-    static getEntitiesForUser(userId: string): Promise<any[]>;
-    static checkIsValidType(entityType: string): boolean;
-    static getEntityManagerClass(entityType?: string): any;
-
-    static getEntityManagerInstanceFromEntityId(
-      entityId: string,
-      userId: string
-    ): Promise<any>;
-  }
-
-  interface IFriggEntityManager {}
-
-  export class Entity extends Model {
-    credentialId: string;
-    subType: string;
-    userId: string;
-    name: string;
-    externalId: string;
+  export interface Entity {
+    id?: string;
+    credentialId?: string;
+    userId?: string;
+    name?: string;
+    moduleName?: string;
+    externalId?: string;
+    data?: any;
   }
 
   export type MappedEntity = Entity & { id: string; type: any };
-  export class ModuleManager extends Delegate implements IFriggModuleManager {
-    static Entity: Entity;
-    static Credential: Credential;
 
-    constructor(params: { userId: string });
-
-    static getName(): any;
-    static getInstance(params: any): Promise<any>;
-    static getEntitiesForUserId(userId: string): Promise<MappedEntity[]>;
-
-    batchCreateSyncObjects(syncObjects: any, syncManager: any): Promise<any>;
-    batchUpdateSyncObjects(syncObjects: any, syncManager: any): Promise<any>;
-    findOrCreateEntity(params: any): Promise<any>;
-    getAllSyncObjects(SyncClass: any): Promise<any>;
-    getAuthorizationRequirements(params: any): Promise<any>;
-    getEntityId(): Promise<string>;
-    getEntityOptions(): Promise<any>;
-    markCredentialsInvalid(): Promise<Credential>;
-    processAuthorizationCallback(params: any): Promise<any>;
-    testAuth(params: any): Promise<any>;
-    validateAuthorizationRequirements(): Promise<boolean>;
-  }
-
-  interface IFriggModuleManager extends IFriggDelegate {
-    getEntityId(): Promise<string>;
-    validateAuthorizationRequirements(): Promise<boolean>;
-    getAuthorizationRequirements(params: any): Promise<any>;
-    testAuth(params: any): Promise<any>;
-    processAuthorizationCallback(params: any): Promise<any>;
-    getEntityOptions(): Promise<any>;
-    findOrCreateEntity(params: any): Promise<any>;
-    getAllSyncObjects(SyncClass: any): Promise<any>;
-    batchCreateSyncObjects(syncObjects: any, syncManager: any): Promise<any>;
-    batchUpdateSyncObjects(syncObjects: any, syncManager: any): Promise<any>;
-    markCredentialsInvalid(): Promise<Credential>;
-  }
 
   export class Requester implements IFriggRequester {
     DLGT_INVALID_AUTH: string;
@@ -90,6 +41,7 @@ declare module "@friggframework/module-plugin" {
     ): Promise<any>;
     parseBody(response: any): Promise<any>;
     refreshAuth(): Promise<any>;
+    _adoptNewerCredential(): Promise<boolean>;
 
     delegate: any;
     delegateTypes: any[];
@@ -121,6 +73,7 @@ declare module "@friggframework/module-plugin" {
     _put(options: RequestOptions): Promise<any>;
     _delete(options: RequestOptions): Promise<any>;
     refreshAuth(): Promise<any>;
+    _adoptNewerCredential(): Promise<boolean>;
   }
 
   type RequestOptions = {
@@ -138,8 +91,7 @@ declare module "@friggframework/module-plugin" {
 
   export class ApiKeyRequester
     extends Requester
-    implements IFriggApiKeyRequester
-  {
+    implements IFriggApiKeyRequester {
     API_KEY_NAME: string;
     API_KEY_VALUE: any;
 
@@ -160,8 +112,7 @@ declare module "@friggframework/module-plugin" {
 
   export class BasicAuthRequester
     extends Requester
-    implements IFriggBasicAuthRequester
-  {
+    implements IFriggBasicAuthRequester {
     password: string;
     username: string;
 
@@ -189,8 +140,7 @@ declare module "@friggframework/module-plugin" {
 
   export class OAuth2Requester
     extends Requester
-    implements IFriggOAuth2Requester
-  {
+    implements IFriggOAuth2Requester {
     DLGT_TOKEN_DEAUTHORIZED: string;
     DLGT_TOKEN_UPDATE: string;
     accessTokenExpire: any;
@@ -253,6 +203,7 @@ declare module "@friggframework/module-plugin" {
     addAuthHeaders(headers: object): Promise<object>;
     isAuthenticated(): boolean;
     refreshAuth(): Promise<void>;
+    _adoptNewerCredential(): Promise<boolean>;
     getTokenFromUsernamePassword(): Promise<Token>;
     getTokenFromClientCredentials(): Promise<Token>;
   }

package/types/syncs/index.d.ts

@@ -1,18 +1,3 @@
-declare module "@friggframework/syncs/model" {
-  import { Model } from "mongoose";
-
-  export class Sync extends Model {
-    entities: any[];
-    hash: string;
-    name: string;
-    dataIdentifiers: {
-      entity: any;
-      id: object;
-      hash: string;
-    }[];
-  }
-}
-
 declare module "@friggframework/syncs/manager" {
   import Sync from "@friggframework/syncs/sync";
 
@@ -28,7 +13,6 @@ declare module "@friggframework/syncs/manager" {
     confirmCreate(
       syncObj: Sync,
       createdId: string,
-      moduleManager: any
     ): Promise<any>;
     confirmUpdate(syncObj: Sync): Promise<any>;
     createSyncDBObject(objArr: any[], entities: any[]): Promise<any>;
@@ -50,7 +34,6 @@ declare module "@friggframework/syncs/manager" {
     confirmCreate(
       syncObj: Sync,
       createdId: string,
-      moduleManager: any
     ): Promise<any>;
     confirmUpdate(syncObj: Sync): Promise<any>;
   }

package/usage/README.md

@@ -0,0 +1,54 @@
+# Usage Store
+
+The durable, Frigg-owned store behind ADR-011 feature-usage tracking. Holds
+per-integration counters that the reporting endpoint reads for cross-integration
+comparison and trend series.
+
+Populated by the telemetry usage rollup and read via `frigg.usage.*` — see
+[`telemetry/README.md`](../telemetry/README.md) for the full guide, config, and
+usage examples. This README covers the store internals only.
+
+## Fact row
+
+`UsageCounter { integrationId, integrationType, metric, window, value, updatedAt }`,
+uniquely keyed by `(integrationId, integrationType, metric, window)`. `window` is
+`day:YYYY-MM-DD` or `hour:YYYY-MM-DDTHH` (UTC).
+
+## Isolation (ADR-010 Decision 3)
+
+The store is deliberately isolated from user/integration-scoped data:
+
+- **No `userId`** and **no foreign key** to `Integration` — a user-scoped query
+  can never return a usage row, and usage history survives integration deletion.
+- **Not** in the encryption registry — dimensions are bounded and non-sensitive.
+
+## Repository triad
+
+Mirrors the reporting/process pattern — an interface plus PostgreSQL, MongoDB and
+DocumentDB adapters selected by `DB_TYPE`:
+
+```js
+const { createUsageRepository } = require('@friggframework/core'); // usage-repository-factory
+
+class UsageRepositoryInterface {
+    async increment({ integrationId, integrationType, metric, window, value }) {} // atomic upsert
+    async getTotalsByDimension({ metric, groupBy, since, bucket }) {}   // comparison (one window granularity)
+    async getTimeSeries({ metric, integrationType, from, to, bucket }) {} // trend (aggregated across instances)
+}
+```
+
+- **`increment`** is atomic: PostgreSQL uses Prisma `upsert` with
+  `{ value: { increment } }`; a concurrent first-insert race (`P2002`) retries
+  once onto the atomic update path.
+- **`getTotalsByDimension`** filters to a single window granularity (default `day`) so day and
+  hour rows are never double-summed. Requires a `metric`; `groupBy` is
+  allow-listed to `integrationType` / `metric`.
+- **`getTimeSeries`** aggregates across integration instances (`groupBy(window) + sum`)
+  and range-filters on the window key. Requires an `integrationType`.
+
+> **DocumentDB:** the adapter overrides increment/getTotalsByDimension/getTimeSeries with raw commands
+> (`$runCommandRaw`: a `$inc` upsert via `documentdb-utils.updateOne`, and a
+> cursor-drained `$aggregate` `$group/$sum`) — matching every other DocumentDB
+> adapter, since Prisma's Mongo engine emits upsert/groupBy shapes DocumentDB
+> rejects and cursor reads truncate at ~101 docs. Command shapes are unit-tested;
+> run an end-to-end check against a real cluster before GA.

package/usage/index.js

@@ -0,0 +1,17 @@
+const {
+    createUsageRepository,
+    UsageRepositoryPrisma,
+    UsageRepositoryDocumentDB,
+} = require('./repositories/usage-repository-factory');
+const {
+    UsageRepositoryInterface,
+} = require('./repositories/usage-repository-interface');
+const { computeTrackedMetrics } = require('./tracked-metrics');
+
+module.exports = {
+    createUsageRepository,
+    computeTrackedMetrics,
+    UsageRepositoryInterface,
+    UsageRepositoryPrisma,
+    UsageRepositoryDocumentDB,
+};

package/usage/repositories/usage-repository-documentdb.js

@@ -0,0 +1,194 @@
+const { prisma } = require('../../database/prisma');
+const { updateOne } = require('../../database/documentdb-utils');
+const { UsageRepositoryPrisma } = require('./usage-repository-prisma');
+const { windowKey } = require('../usage-windows');
+
+const COLLECTION = 'UsageCounter';
+const DRAIN_BATCH_SIZE = 1000;
+const MAX_BATCHES = 100000;
+const VALID_GROUP_BY = new Set(['integrationType', 'metric']);
+const VALID_BUCKETS = new Set(['day', 'hour']);
+
+/**
+ * DocumentDB usage store. Amazon DocumentDB does not accept the command shapes
+ * Prisma's Mongo engine emits for `upsert({ update: { value: { increment } } })`
+ * and `groupBy({ _sum })`, and cursor reads truncate at ~101 docs — so, like
+ * every other DocumentDB adapter in this repo, these operations are issued as
+ * raw commands (`$runCommandRaw`) via the validated documentdb-utils helpers and
+ * a drained aggregate cursor. No timestamps are managed: getTotalsByDimension/getTimeSeries filter on
+ * the window KEY (not write-time), so createdAt/updatedAt are unnecessary here.
+ */
+class UsageRepositoryDocumentDB extends UsageRepositoryPrisma {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    async increment({ integrationId, integrationType, metric, window, value = 1 }) {
+        // Atomic upsert-increment: $inc creates the field at the increment value
+        // on insert; $setOnInsert stamps the identity on first write. The compound
+        // filter is the unique key, so concurrent writers converge on one row.
+        await updateOne(
+            this.prisma,
+            COLLECTION,
+            { integrationId, integrationType, metric, window },
+            {
+                $inc: { value },
+                $setOnInsert: {
+                    integrationId,
+                    integrationType,
+                    metric,
+                    window,
+                },
+            },
+            { upsert: true }
+        );
+    }
+
+    async getTotalsByDimension({
+        metric,
+        groupBy = 'integrationType',
+        since,
+        bucket = 'day',
+    } = {}) {
+        if (!metric) {
+            throw new Error('getTotalsByDimension requires a metric (units are per-metric)');
+        }
+        assertGroupBy(groupBy);
+        assertBucket(bucket);
+
+        // Single window granularity (day: OR hour:) — never sum across both.
+        // `since` bounds on the window KEY (mirrors getTimeSeries / the Prisma adapter).
+        const rows = await this._aggregateDrained([
+            {
+                $match: {
+                    metric,
+                    window: windowMatch(bucket, {
+                        gte: since ? windowKey(bucket, since) : undefined,
+                    }),
+                },
+            },
+            { $group: { _id: `$${groupBy}`, value: { $sum: '$value' } } },
+        ]);
+
+        return rows.map((row) => ({
+            [groupBy]: row._id,
+            value: toNumber(row.value),
+        }));
+    }
+
+    async getTimeSeries({ metric, integrationType, from, to, bucket = 'day' } = {}) {
+        assertBucket(bucket);
+        if (!integrationType) {
+            throw new Error('getTimeSeries requires an integrationType');
+        }
+
+        const rows = await this._aggregateDrained([
+            {
+                $match: {
+                    metric,
+                    integrationType,
+                    window: windowMatch(bucket, {
+                        gte: from ? windowKey(bucket, from) : undefined,
+                        lte: to ? windowKey(bucket, to) : undefined,
+                    }),
+                },
+            },
+            { $group: { _id: '$window', value: { $sum: '$value' } } },
+            { $sort: { _id: 1 } },
+        ]);
+
+        return rows.map((row) => ({
+            bucket: row._id,
+            value: toNumber(row.value),
+        }));
+    }
+
+    async _aggregateDrained(pipeline) {
+        const first = await this.prisma.$runCommandRaw({
+            aggregate: COLLECTION,
+            pipeline,
+            cursor: { batchSize: DRAIN_BATCH_SIZE },
+        });
+        return drainCursor(this.prisma, COLLECTION, first);
+    }
+}
+
+/** A `$match` window clause: prefix by granularity, optionally range-bounded. */
+function windowMatch(bucket, { gte, lte } = {}) {
+    const clause = { $regex: `^${bucket}:` };
+    if (gte) clause.$gte = gte;
+    if (lte) clause.$lte = lte;
+    return clause;
+}
+
+/**
+ * Coerce an aggregate `$sum` result to a JS Number. Prisma $runCommandRaw returns
+ * extended JSON, so a 64-bit sum can arrive as { $numberLong: "..." } (or
+ * $numberInt/$numberDouble); counts never approach 2^53.
+ */
+function toNumber(value) {
+    if (value === null || value === undefined) return 0;
+    if (typeof value === 'number') return value;
+    if (typeof value === 'bigint') return Number(value);
+    if (typeof value === 'object') {
+        const raw =
+            value.$numberLong ?? value.$numberInt ?? value.$numberDouble;
+        if (raw !== undefined) return Number(raw);
+    }
+    return Number(value) || 0;
+}
+
+async function drainCursor(client, collection, firstResult) {
+    const cursor = firstResult?.cursor || {};
+    const docs = [...(cursor.firstBatch || [])];
+    let cursorId = cursor.id;
+    let batches = 0;
+
+    while (isCursorOpen(cursorId) && batches < MAX_BATCHES) {
+        batches += 1;
+        const next = await client.$runCommandRaw({
+            getMore: cursorId,
+            collection,
+            batchSize: DRAIN_BATCH_SIZE,
+        });
+        const nextCursor = next?.cursor || {};
+        const nextBatch = nextCursor.nextBatch || [];
+        docs.push(...nextBatch);
+        cursorId = nextCursor.id;
+        if (nextBatch.length === 0) break;
+    }
+    return docs;
+}
+
+function isCursorOpen(id) {
+    if (id === undefined || id === null) return false;
+    if (typeof id === 'number') return id !== 0;
+    if (typeof id === 'bigint') return id !== 0n;
+    if (typeof id === 'object' && id.$numberLong !== undefined) {
+        return id.$numberLong !== '0';
+    }
+    return String(id) !== '0';
+}
+
+function assertGroupBy(groupBy) {
+    if (!VALID_GROUP_BY.has(groupBy)) {
+        throw new Error(
+            `Invalid groupBy "${groupBy}". Allowed: ${[...VALID_GROUP_BY].join(
+                ', '
+            )}`
+        );
+    }
+}
+
+function assertBucket(bucket) {
+    if (!VALID_BUCKETS.has(bucket)) {
+        throw new Error(
+            `Invalid bucket "${bucket}". Allowed: ${[...VALID_BUCKETS].join(
+                ', '
+            )}`
+        );
+    }
+}
+
+module.exports = { UsageRepositoryDocumentDB };

package/usage/repositories/usage-repository-factory.js

@@ -0,0 +1,25 @@
+const { UsageRepositoryPrisma } = require('./usage-repository-prisma');
+const { UsageRepositoryDocumentDB } = require('./usage-repository-documentdb');
+const config = require('../../database/config');
+
+function createUsageRepository() {
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+        case 'postgresql':
+            return new UsageRepositoryPrisma();
+        case 'documentdb':
+            return new UsageRepositoryDocumentDB();
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createUsageRepository,
+    UsageRepositoryPrisma,
+    UsageRepositoryDocumentDB,
+};

package/usage/repositories/usage-repository-interface.js

@@ -0,0 +1,37 @@
+/**
+ * Port for the durable usage-counter store.
+ *
+ * The store is deliberately isolated (ADR-010 Decision 3): its fact rows carry
+ * NO userId and NO foreign key to Integration, so a user-scoped query can never
+ * return a usage row and usage history survives integration deletion.
+ *
+ * Fact row: { integrationId, integrationType, metric, window, value, updatedAt }
+ * Dimensions must be bounded — high-cardinality ids stay on traces.
+ */
+class UsageRepositoryInterface {
+    /**
+     * Atomically add `value` to the counter for
+     * (integrationId, integrationType, metric, window), inserting if absent.
+     */
+    async increment(/* { integrationId, integrationType, metric, window, value } */) {
+        throw new Error('increment must be implemented by subclass');
+    }
+
+    /**
+     * Sum a metric grouped by a bounded dimension since an optional timestamp.
+     * @returns {Promise<Array<{[groupBy]: string, value: number}>>}
+     */
+    async getTotalsByDimension(/* { metric, groupBy, since } */) {
+        throw new Error('getTotalsByDimension must be implemented by subclass');
+    }
+
+    /**
+     * Time series of a metric for one integration type.
+     * @returns {Promise<Array<{bucket: string, value: number}>>}
+     */
+    async getTimeSeries(/* { metric, integrationType, from, to, bucket } */) {
+        throw new Error('getTimeSeries must be implemented by subclass');
+    }
+}
+
+module.exports = { UsageRepositoryInterface };

package/usage/repositories/usage-repository-prisma.js

@@ -0,0 +1,146 @@
+const { prisma } = require('../../database/prisma');
+const { UsageRepositoryInterface } = require('./usage-repository-interface');
+const { windowKey } = require('../usage-windows');
+
+/**
+ * Prisma-backed usage store — the single implementation for both mongodb and
+ * postgresql (Prisma abstracts the store; integrationId is a plain string in
+ * both). DocumentDB extends this but overrides the write/read ops with raw
+ * commands. All queries touch only the isolated `UsageCounter` model — never
+ * user/integration-scoped tables.
+ */
+class UsageRepositoryPrisma extends UsageRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    async increment({
+        integrationId,
+        integrationType,
+        metric,
+        window,
+        value = 1,
+    }) {
+        const where = {
+            integrationId_integrationType_metric_window: {
+                integrationId,
+                integrationType,
+                metric,
+                window,
+            },
+        };
+        const upsertArgs = {
+            where,
+            create: { integrationId, integrationType, metric, window, value },
+            update: { value: { increment: value } },
+        };
+
+        // Concurrent first-insert race: two workers both INSERT and one hits the
+        // unique constraint (P2002). After the winner's insert the row exists, so
+        // a retry takes the atomic UPDATE (increment) path. Bounded so a
+        // pathological repeated race can't throw unexpectedly out of the public
+        // `recordUsageCounter` write; non-conflict errors surface immediately.
+        for (let attempt = 1; ; attempt++) {
+            try {
+                await this.prisma.usageCounter.upsert(upsertArgs);
+                return;
+            } catch (err) {
+                if (err && err.code === 'P2002' && attempt < MAX_UPSERT_ATTEMPTS) {
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+
+    async getTotalsByDimension({
+        metric,
+        groupBy = 'integrationType',
+        since,
+        bucket = 'day',
+    } = {}) {
+        if (!metric) {
+            throw new Error('getTotalsByDimension requires a metric (units are per-metric)');
+        }
+        assertGroupBy(groupBy);
+        assertBucket(bucket);
+
+        // Filter to ONE window granularity — every event is written to both a
+        // day: and an hour: row, so summing across granularities would double
+        // (or worse) the true count.
+        // Bound `since` on the WINDOW key (mirrors getTimeSeries) — write-time
+        // updatedAt would misplace a late/redelivered increment for an earlier
+        // window, over- or under-counting the time-bounded total.
+        const where = { metric, window: { startsWith: `${bucket}:` } };
+        if (since) where.window.gte = windowKey(bucket, since);
+
+        const groups = await this.prisma.usageCounter.groupBy({
+            by: [groupBy],
+            where,
+            _sum: { value: true },
+        });
+
+        // value is a BigInt column — coerce the sum to a JSON-safe Number
+        // (JSON.stringify throws on BigInt; counts never approach 2^53).
+        return groups.map((group) => ({
+            [groupBy]: group[groupBy],
+            value: Number(group._sum?.value ?? 0),
+        }));
+    }
+
+    async getTimeSeries({ metric, integrationType, from, to, bucket = 'day' } = {}) {
+        assertBucket(bucket);
+        if (!integrationType) {
+            throw new Error('getTimeSeries requires an integrationType');
+        }
+
+        // Range-filter on the WINDOW key (write-time `updatedAt` would misplace a
+        // late increment for an earlier window). Window keys are ISO-lexicographic
+        // within a granularity, so string gte/lte gives the correct range.
+        const window = { startsWith: `${bucket}:` };
+        if (from) window.gte = windowKey(bucket, from);
+        if (to) window.lte = windowKey(bucket, to);
+
+        // Aggregate ACROSS integration instances: there is one row per
+        // (integrationId, integrationType, metric, window), so a type with many
+        // instances has many rows per window — sum them into one point.
+        const groups = await this.prisma.usageCounter.groupBy({
+            by: ['window'],
+            where: { metric, integrationType, window },
+            _sum: { value: true },
+            orderBy: { window: 'asc' },
+        });
+
+        return groups.map((group) => ({
+            bucket: group.window,
+            value: Number(group._sum?.value ?? 0),
+        }));
+    }
+}
+
+const MAX_UPSERT_ATTEMPTS = 3;
+const VALID_GROUP_BY = new Set(['integrationType', 'metric']);
+const VALID_BUCKETS = new Set(['day', 'hour']);
+
+function assertGroupBy(groupBy) {
+    if (!VALID_GROUP_BY.has(groupBy)) {
+        throw new Error(
+            `Invalid groupBy "${groupBy}". Allowed: ${[...VALID_GROUP_BY].join(
+                ', '
+            )}`
+        );
+    }
+}
+
+function assertBucket(bucket) {
+    if (!VALID_BUCKETS.has(bucket)) {
+        throw new Error(
+            `Invalid bucket "${bucket}". Allowed: ${[...VALID_BUCKETS].join(
+                ', '
+            )}`
+        );
+    }
+}
+
+module.exports = { UsageRepositoryPrisma };

package/usage/tracked-metrics.js

@@ -0,0 +1,38 @@
+const { isCanonicalCounter } = require('../telemetry/canonical-counters');
+
+/**
+ * Compute the set of usage-counter keys the rollup should persist, from each
+ * integration's `Definition.usage` opt-in.
+ * Declaring a canonical key opts into cross-type comparison + the rollup; custom
+ * keys are tracked per integration type. Unknown canonical keys are dropped with
+ * a warning (lazy validation, matching how Definition is treated elsewhere).
+ */
+function computeTrackedMetrics(integrationClasses = []) {
+    const tracked = new Set();
+    if (!Array.isArray(integrationClasses)) return tracked;
+
+    for (const IntegrationClass of integrationClasses) {
+        const usage = IntegrationClass?.Definition?.usage;
+        if (!usage) continue;
+        const name = IntegrationClass.Definition?.name || 'integration';
+
+        for (const key of usage.canonical || []) {
+            if (!isCanonicalCounter(key)) {
+                console.warn(
+                    `[Frigg][usage] "${name}" declares unknown canonical counter "${key}" — ignored. ` +
+                        `Use a key from CANONICAL_COUNTERS or declare it under usage.custom.`
+                );
+                continue;
+            }
+            tracked.add(key);
+        }
+
+        for (const key of Object.keys(usage.custom || {})) {
+            tracked.add(key);
+        }
+    }
+
+    return tracked;
+}
+
+module.exports = { computeTrackedMetrics };