npm - @jeffjassky/telemetry - Versions diffs - 0.4.0 → 0.6.0 - Mend

@jeffjassky/telemetry 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/dist/index.cjs +319 -45
package/dist/index.cjs.map +1 -1
package/dist/index.js +317 -46
package/dist/index.js.map +1 -1
package/dist/mcp.cjs.map +1 -1
package/dist/mcp.js.map +1 -1
package/dist/ui/_assets/index-kvwB9_3A.js +41 -0
package/dist/ui/_assets/{index-Deqhu-hT.js.map → index-kvwB9_3A.js.map} +1 -1
package/dist/ui/index.html +1 -1
package/package.json +1 -1
package/types/index.d.ts +162 -0
package/types/test-d.ts +38 -0
package/dist/ui/_assets/index-Deqhu-hT.js +0 -41

package/dist/ui/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Telemetry</title>
     <!--telemetry-config-->
-    <script type="module" crossorigin src="./_assets/index-Deqhu-hT.js"></script>
+    <script type="module" crossorigin src="./_assets/index-kvwB9_3A.js"></script>
     <link rel="stylesheet" crossorigin href="./_assets/index-COswHpSX.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@jeffjassky/telemetry",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Unified telemetry — product events, errors, traces, state transitions, and billable usage in one Mongo envelope, with typed SDKs and a mountable dashboard.",
   "license": "MIT",
   "author": "Jeff Jassky <jeff@jeffjassky.com>",

package/types/index.d.ts CHANGED Viewed

@@ -632,6 +632,24 @@ export interface TelemetryCounters {
    * not stripped; this groups what the quarantine lists one row at a time.
    */
   undeclaredAttrs: Record<string, number>;
+  /**
+   * Write-time subject linking. All six stay at zero without a
+   * `subjectLinker`. They are split six ways because every way linking can fail
+   * ends in the same row — one written with the subjects it arrived with — and
+   * a silently unlinked record is indistinguishable from one nobody could link.
+   */
+  /** subjects actually ADDED to records — two links on one record count twice */
+  subjectsLinked: number;
+  /** records where the linker answered `[]` — no link exists, which is an answer */
+  subjectLinkMisses: number;
+  /** the linker threw, rejected, or returned something that is not a list of refs */
+  subjectLinkErrors: number;
+  /** the linker outran `subjectLinkTimeoutMs`; the record was written unlinked */
+  subjectLinkTimeouts: number;
+  /** a linked subject whose `type` the event's `EventSpec.subjects` does not declare */
+  subjectLinkUndeclared: number;
+  /** a linked subject dropped because the record already held `SUBJECT_MAX` of them */
+  subjectLinkCapped: number;
 }
 /**
@@ -678,6 +696,59 @@ export interface ForgetResult {
   views: number;
 }
+export interface RelinkOptions {
+  /**
+   * Restrict to these event names. Default: every stored record, whatever its
+   * name. A name the registry does not declare THROWS, before any I/O — a typo
+   * that silently relinks nothing looks exactly like a clean run.
+   */
+  names?: string[];
+  /** only records at/after this instant (`occurredAt`) */
+  since?: Date;
+  /**
+   * Stop after this many records are EXAMINED — not linked. A budget for the
+   * scan, so a huge collection can be probed cheaply. Default unbounded.
+   */
+  limit?: number;
+  /**
+   * Report what would change and write NOTHING. **Defaults to `true`**, because
+   * this rewrites historical aggregates and the short call has to be the safe
+   * one. A dry run still asks the host's linker, so the linking counters move;
+   * nothing on disk does.
+   */
+  dryRun?: boolean;
+  /** records fetched per batch, and the `onProgress` cadence. Default 500. */
+  batchSize?: number;
+  /** cumulative counts after each batch, for progress output. Guarded: a
+   *  printer that throws does not kill the backfill. */
+  onProgress?: (r: RelinkResult) => void;
+}
+export interface RelinkResult {
+  /** rows read */
+  examined: number;
+  /** rows that gained at least one subject */
+  linked: number;
+  /** subjects added in total — two links on one row count twice */
+  subjects: number;
+  /** rollup documents written, or under `dryRun` that would have been */
+  rollups: number;
+  /** rows where the linker answered `[]`. On a backfill this is the expected
+   *  answer for most rows, and it is not a failure. */
+  misses: number;
+  /** rows where the linker threw, rejected, timed out or answered garbage —
+   *  once per ROW however many ways it went wrong. `counters.subjectLinkErrors`
+   *  and `subjectLinkTimeouts` keep the finer split. */
+  errors: number;
+  /** rows the run declined to offer the linker (a stored name the registry no
+   *  longer declares, so its rollup families are unknowable), plus one standing
+   *  for a call with no `subjectLinker` configured, which reads nothing. */
+  skipped: number;
+}
+/** records fetched per batch by `relink()`, and how often `onProgress` fires */
+export declare const RELINK_BATCH_SIZE: 500;
 export interface Scoped {
   find(q?: Record<string, unknown>): Query<any[], any>;
   aggregate(stages: Record<string, unknown>[]): Aggregate<any[]>;
@@ -709,9 +780,73 @@ export interface CreateTelemetryConfig<R extends Registry = Registry> {
    * different person in each, and one tenant's erasure would reach another's.
    */
   globalSubjectRefs?: boolean;
+  /**
+   * Attach additional subjects to a record AT WRITE TIME — the desktop
+   * `machine:<installId>` the host can resolve to a `user`, joined once, onto
+   * the row and its rollups, rather than at every read that ever wants it.
+   * Must be cached: it runs once per record on the ingest path.
+   */
+  subjectLinker?: SubjectLinker;
+  /**
+   * What `subjectLinker.link()` gets per record before the write proceeds
+   * UNLINKED and counts a timeout. Default 50.
+   */
+  subjectLinkTimeoutMs?: number;
   logger?: Logger;
 }
+/**
+ * WRITE-time subject linking — distinct from `SubjectAdapter`, which labels
+ * refs at read time and changes nothing about what is stored.
+ *
+ * A desktop client knows its install and nothing else, so its records carry
+ * `machine:<installId>` and no `user`. Resolving that at read time leaves a
+ * cohort funnel anchored on `user` reading zero for every desktop stage;
+ * resolving it at write time puts the party on the row AND on its rollups,
+ * which is the half a read-time join can never reach.
+ */
+export interface SubjectLinker {
+  /**
+   * Additional subjects for a record being written. `[]` when nothing links —
+   * that is an answer, and it is counted as one.
+   *
+   * Runs once per record on the write path, so it must answer from a cache.
+   * The package bounds it rather than trusting it: past `subjectLinkTimeoutMs`,
+   * or on a throw, the record is written unlinked and counted. A linked subject
+   * whose `type` the event does not declare is written ANYWAY and counted in
+   * `counters.subjectLinkUndeclared` — refusing it could only ever be obeyed by
+   * losing rows, because `EventSpec.subjects` is a required list.
+   */
+  link(
+    subjects: SubjectInput[],
+    ctx: { name: string; tenantId: string },
+  ): SubjectInput[] | Promise<SubjectInput[]>;
+}
+/**
+ * The guarded linker the instance resolved at construction: the merged subjects
+ * to write, or `null` when nothing changed. Exposed as `t.linkSubjects` for the
+ * router factories, which reach it the way they reach the registry.
+ */
+export type LinkSubjects = (
+  name: string,
+  spec: { subjects: readonly string[] },
+  tenantId: string,
+  declared: unknown,
+) => Promise<SubjectInput[] | null>;
+/**
+ * Total subjects one record may carry once linking has run. `subjectKeys` is a
+ * multikey index term and every subject fans a `by:['subject']` rollup out one
+ * more time, so an unbounded array is unbounded write amplification with a
+ * host's cache bug behind it. Overflow is dropped and counted in
+ * `counters.subjectLinkCapped`.
+ */
+export declare const SUBJECT_MAX: 8;
+/** default `subjectLinkTimeoutMs` — past it the record is written unlinked */
+export declare const SUBJECT_LINK_TIMEOUT_MS: 50;
 export interface Telemetry<R extends Registry = Registry> {
   /** write — the only write. The result says what actually happened to the row. */
   emit<N extends keyof R & string>(name: N, doc: EmitInput<R, N>): Promise<EmitResult>;
@@ -722,6 +857,25 @@ export interface Telemetry<R extends Registry = Registry> {
    * platform-scoped saved views only when `globalSubjectRefs` is set.
    */
   forget(tenantId: string, ref: EntityRef): Promise<ForgetResult>;
+  /**
+   * Backfill for `subjectLinker`: re-ask it about records ALREADY on disk, and
+   * replay the rollups the new subjects reach.
+   *
+   * Linking happens at write time, so configuring the hook fixes the future and
+   * nothing else — a lifetime `by:['subject']` family is keyed on the subject
+   * the record was written with, permanently, and no read-time join can reach
+   * back into it. A host that adopts linking on a Tuesday therefore has a
+   * backlog whose rows carry only `machine:<installId>` and whose user-keyed
+   * families have no member for any of them. This is how it catches up.
+   *
+   * **Dry run by default.** It rewrites historical aggregates, so `t.relink()`
+   * reports and `t.relink({ dryRun: false })` writes. Idempotent by
+   * construction: a row that already carries the linked subject yields nothing
+   * new, so a second run writes nothing and replays nothing. Returns
+   * `{ skipped: 1 }` rather than throwing when no `subjectLinker` is
+   * configured.
+   */
+  relink(opts?: RelinkOptions): Promise<RelinkResult>;
   /**
    * Tenant scope is not optional — every read goes through here. Unconditional
    * on purpose: it does not understand PLATFORM_SCOPE, so `scoped('*')` scopes
@@ -739,6 +893,14 @@ export interface Telemetry<R extends Registry = Registry> {
   counters: TelemetryCounters;
   /** the registry this instance validates against */
   registry: R;
+  /**
+   * Write-time subject linking, guarded and resolved once at construction;
+   * `null` without a `subjectLinker`. Exposed for the router factories: the
+   * wire path does not go through `emit()` — at-least-once delivery inverts the
+   * plane order — so `createIngest` reaches the one implementation here rather
+   * than growing a second copy of the rules.
+   */
+  linkSubjects: LinkSubjects | null;
   logger: Logger;
   /** mint an ingest key against this instance's key collection */
   createKey(input: CreateKeyInput): Promise<{ key: string; id: string }>;

package/types/test-d.ts CHANGED Viewed

@@ -33,9 +33,13 @@ import type {
   Logger,
   MetricsOf,
   Registry,
+  RelinkOptions,
+  RelinkResult,
   RollupSpec,
+  LinkSubjects,
   Scoped,
   SubjectInput,
+  SubjectLinker,
   Telemetry,
   TelemetryCounters,
 } from './index.js';
@@ -58,9 +62,12 @@ import {
   LogLevel,
   Origin,
   PLATFORM_SCOPE,
+  RELINK_BATCH_SIZE,
   RETENTION_DAYS,
   SAMPLE_RATE,
   SCHEMA_VERSION,
+  SUBJECT_LINK_TIMEOUT_MS,
+  SUBJECT_MAX,
   TelemetryKind,
 } from './index.js';
@@ -101,6 +108,15 @@ const registry = defineRegistry({
 declare const mongooseish: CreateTelemetryConfig['connection'];
+/** WRITE-time: the desktop's machine ref, resolved to the account that owns it */
+const subjectLinker: SubjectLinker = {
+  link: async (subjects, { name, tenantId }) => {
+    void name, tenantId;
+    const machine = subjects.find((s) => s.type === 'machine');
+    return machine ? [{ type: 'user', id: `u_${machine.id}`, role: 'owner' }] : [];
+  },
+};
 const t = createTelemetry({
   registry,
   connection: mongooseish,
@@ -108,8 +124,15 @@ const t = createTelemetry({
   platforms: ['watchos'], // EXTENDS the builtins; 'web' still validates
   bodyMax: 4096,
   globalSubjectRefs: true, // refs name one party in every tenant — forget() reaches '*' views
+  subjectLinker,
+  subjectLinkTimeoutMs: SUBJECT_LINK_TIMEOUT_MS,
 });
+// the guarded linker the instance resolved, shared with the router factories
+const linkSubjects: LinkSubjects | null = t.linkSubjects;
+const subjectCap: number = SUBJECT_MAX;
+void linkSubjects, subjectCap;
 // ── emit is typed against the registry ──
 async function writes() {
   await t.emit('user.signed_up', {
@@ -176,6 +199,21 @@ async function reads() {
   const gone: ForgetResult = await t.forget('acc_9', 'user:u_1');
   void (gone.deleted + gone.redacted + gone.rollups + gone.aliases);
+  // relink() — the backfill for subjectLinker. Dry run by DEFAULT, so the
+  // no-argument call is the safe one and writing is opted into.
+  const preview: RelinkResult = await t.relink();
+  const opts: RelinkOptions = {
+    names: ['user.signed_up'],
+    since: new Date('2026-01-01T00:00:00Z'),
+    limit: 10_000,
+    dryRun: false,
+    batchSize: RELINK_BATCH_SIZE,
+    onProgress: (p) => void p.examined,
+  };
+  const done: RelinkResult = await t.relink(opts);
+  void (preview.examined + done.linked + done.subjects + done.rollups
+    + done.misses + done.errors + done.skipped);
   const cp: Checkpoint = t.checkpoint('mailery-bridge');
   const mark: Date | null = await cp.get();
   await cp.advance(mark ?? new Date());