@lp-labs/sync-observability 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# @lp-labs/sync-observability
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bounded numeric synchronization metrics and payload-free diagnostics.
+
+Original independent MIT TypeScript implementation with **zero runtime/peer dependencies**. ESM and CommonJS with separate declarations, Node 18+ (browser use when adapters/APIs are available). Development dependencies are not consumer runtime dependencies.
+
+## Install
+
+```sh
+npm install @lp-labs/sync-observability
+```
+
+## Complete example
+
+```js
+import assert from 'node:assert/strict';
+import { createSyncObservability, SyncObservabilityError } from '@lp-labs/sync-observability';
+const monitor = createSyncObservability({ maxEvents: 2, staleAfterMs: 10 });
+monitor.record({ kind: 'queue', at: 1, queueSize: 2 });
+monitor.record({ kind: 'completed', at: 2 });
+assert.equal(monitor.metrics(2).health, 'healthy');
+assert.equal(monitor.metrics(13).health, 'stale');
+assert.equal(monitor.exportDiagnostics(2).metrics.completed, 1);
+```
+
+CommonJS exposes the same API: `const api = require('@lp-labs/sync-observability')`.
+
+## Scope, customization and performance
+
+Allowlisted kinds and numeric signals only: unknown fields reject rather than silently redact. No identifiers, payloads or labels stored. Ring history default 200 events; lifetime counters retain totals. Explicit now recommended for deterministic tests. Events must be nondecreasing; future observations relative to now are rejected. Queue threshold defaults 10,000. Health precedence stale/backlogged/conflicted/healthy; failures are separate counters, not an automatic outage classification.
+
+Configure explicit limits, clocks, policies and adapters through the API below. Error classes and standard TypeError/RangeError reject malformed input; adapter/handler errors propagate. Await asynchronous methods and handle rejection in your application; no success-shaped fallback on failed work. Inputs must be trusted ordinary data, not hostile proxies; adapters must meet documented atomicity, isolation and ownership contracts. This package never publishes data, loads external code or starts background services at import time.
+
+## API reference
+
+The complete exported TypeScript contract (including option defaults discussed above, method return shapes, and error codes) is included below. TypeScript users import interfaces using `import type`; JavaScript users pass matching ordinary objects. Signature optionals indicate intentionally optional fields, not silent recovery.
+
+```ts
+export type ObservationKind =
+  'started' | 'completed' | 'failed' | 'conflict' | 'queue' | 'checkpoint';
+export type SyncHealth = 'healthy' | 'stale' | 'backlogged' | 'conflicted' | 'unknown';
+export interface SyncObservation {
+  kind: ObservationKind;
+  at: number;
+  lagMs?: number;
+  queueSize?: number;
+}
+export interface SanitizedObservation {
+  kind: ObservationKind;
+  at: number;
+  lagMs: number;
+  queueSize: number;
+}
+export interface SyncMetrics {
+  health: SyncHealth;
+  observedAt: number;
+  lastActivityAt: number | null;
+  lagMs: number;
+  queueSize: number;
+  conflicts: number;
+  failures: number;
+  completed: number;
+}
+export interface DiagnosticExport {
+  format: 'lp-sync-diagnostics';
+  version: 1;
+  metrics: SyncMetrics;
+  observations: SanitizedObservation[];
+  truncated: boolean;
+}
+export interface SyncObservabilityOptions {
+  maxEvents?: number;
+  maxQueueSize?: number;
+  staleAfterMs?: number;
+}
+export declare class SyncObservabilityError extends Error {
+  readonly code: 'invalid' | 'capacity';
+  constructor(code: 'invalid' | 'capacity', message: string);
+}
+export interface SyncObservability {
+  record(observation: SyncObservation): void;
+  metrics(now?: number): SyncMetrics;
+  exportDiagnostics(now?: number): DiagnosticExport;
+}
+/** Keeps only allow-listed numeric sync signals; labels, payloads, and identifiers are never stored. */
+export declare function createSyncObservability(
+  options?: SyncObservabilityOptions,
+): SyncObservability;
+```
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,47 @@
+export type ObservationKind = 'started' | 'completed' | 'failed' | 'conflict' | 'queue' | 'checkpoint';
+export type SyncHealth = 'healthy' | 'stale' | 'backlogged' | 'conflicted' | 'unknown';
+export interface SyncObservation {
+    kind: ObservationKind;
+    at: number;
+    lagMs?: number;
+    queueSize?: number;
+}
+export interface SanitizedObservation {
+    kind: ObservationKind;
+    at: number;
+    lagMs: number;
+    queueSize: number;
+}
+export interface SyncMetrics {
+    health: SyncHealth;
+    observedAt: number;
+    lastActivityAt: number | null;
+    lagMs: number;
+    queueSize: number;
+    conflicts: number;
+    failures: number;
+    completed: number;
+}
+export interface DiagnosticExport {
+    format: 'lp-sync-diagnostics';
+    version: 1;
+    metrics: SyncMetrics;
+    observations: SanitizedObservation[];
+    truncated: boolean;
+}
+export interface SyncObservabilityOptions {
+    maxEvents?: number;
+    maxQueueSize?: number;
+    staleAfterMs?: number;
+}
+export declare class SyncObservabilityError extends Error {
+    readonly code: 'invalid' | 'capacity';
+    constructor(code: 'invalid' | 'capacity', message: string);
+}
+export interface SyncObservability {
+    record(observation: SyncObservation): void;
+    metrics(now?: number): SyncMetrics;
+    exportDiagnostics(now?: number): DiagnosticExport;
+}
+/** Keeps only allow-listed numeric sync signals; labels, payloads, and identifiers are never stored. */
+export declare function createSyncObservability(options?: SyncObservabilityOptions): SyncObservability;

package/dist/cjs/index.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncObservabilityError = void 0;
+exports.createSyncObservability = createSyncObservability;
+class SyncObservabilityError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SyncObservabilityError';
+    }
+}
+exports.SyncObservabilityError = SyncObservabilityError;
+const KINDS = [
+    'started',
+    'completed',
+    'failed',
+    'conflict',
+    'queue',
+    'checkpoint',
+];
+function boundedInteger(value, min, max, label) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min || value > max) {
+        throw new SyncObservabilityError('invalid', `${label} must be a safe integer from ${min} to ${max}.`);
+    }
+    return value;
+}
+function optionsRecord(value) {
+    if (typeof value !== 'object' ||
+        value === null ||
+        Array.isArray(value) ||
+        Object.getPrototypeOf(value) !== Object.prototype ||
+        Object.getOwnPropertySymbols(value).length !== 0) {
+        throw new SyncObservabilityError('invalid', 'Options and observations must be plain objects.');
+    }
+    return value;
+}
+/** Keeps only allow-listed numeric sync signals; labels, payloads, and identifiers are never stored. */
+function createSyncObservability(options = {}) {
+    const rawOptions = optionsRecord(options);
+    if (Object.keys(rawOptions).some((key) => !['maxEvents', 'maxQueueSize', 'staleAfterMs'].includes(key))) {
+        throw new SyncObservabilityError('invalid', 'Options contain an unknown field.');
+    }
+    const maxEvents = boundedInteger(options.maxEvents ?? 200, 1, 10_000, 'maxEvents');
+    const maxQueueSize = boundedInteger(options.maxQueueSize ?? 10_000, 1, 1_000_000, 'maxQueueSize');
+    const staleAfterMs = boundedInteger(options.staleAfterMs ?? 60_000, 0, 86_400_000, 'staleAfterMs');
+    let observations = [];
+    let lagMs = 0;
+    let queueSize = 0;
+    let conflicts = 0;
+    let failures = 0;
+    let completed = 0;
+    let droppedEvents = false;
+    const metrics = (now = Date.now()) => {
+        const observedAt = boundedInteger(now, 0, Number.MAX_SAFE_INTEGER, 'now');
+        const lastActivityAt = observations.at(-1)?.at ?? null;
+        if (lastActivityAt !== null && observedAt < lastActivityAt)
+            throw new SyncObservabilityError('invalid', 'now predates the last observation.');
+        let health = 'unknown';
+        if (lastActivityAt !== null) {
+            health =
+                observedAt - lastActivityAt > staleAfterMs
+                    ? 'stale'
+                    : queueSize >= maxQueueSize
+                        ? 'backlogged'
+                        : conflicts > 0
+                            ? 'conflicted'
+                            : 'healthy';
+        }
+        return { health, observedAt, lastActivityAt, lagMs, queueSize, conflicts, failures, completed };
+    };
+    return {
+        record(input) {
+            const raw = optionsRecord(input);
+            if (Object.keys(raw).some((key) => !['kind', 'at', 'lagMs', 'queueSize'].includes(key))) {
+                throw new SyncObservabilityError('invalid', 'Observation contains an unknown field.');
+            }
+            if (typeof input.kind !== 'string' || !KINDS.includes(input.kind)) {
+                throw new SyncObservabilityError('invalid', 'Observation kind is not supported.');
+            }
+            const at = boundedInteger(input.at, 0, Number.MAX_SAFE_INTEGER, 'at');
+            const nextLag = boundedInteger(input.lagMs ?? 0, 0, Number.MAX_SAFE_INTEGER, 'lagMs');
+            const nextQueue = boundedInteger(input.queueSize ?? 0, 0, maxQueueSize, 'queueSize');
+            const previous = observations.at(-1);
+            if (previous && at < previous.at) {
+                throw new SyncObservabilityError('invalid', 'Observation timestamps must be nondecreasing.');
+            }
+            const safe = { kind: input.kind, at, lagMs: nextLag, queueSize: nextQueue };
+            observations.push(safe);
+            if (observations.length > maxEvents) {
+                observations = observations.slice(-maxEvents);
+                droppedEvents = true;
+            }
+            lagMs = nextLag;
+            queueSize = nextQueue;
+            if (input.kind === 'conflict')
+                conflicts++;
+            if (input.kind === 'failed')
+                failures++;
+            if (input.kind === 'completed')
+                completed++;
+        },
+        metrics,
+        exportDiagnostics(now = Date.now()) {
+            return {
+                format: 'lp-sync-diagnostics',
+                version: 1,
+                metrics: metrics(now),
+                observations: observations.map((entry) => ({ ...entry })),
+                truncated: droppedEvents,
+            };
+        },
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,47 @@
+export type ObservationKind = 'started' | 'completed' | 'failed' | 'conflict' | 'queue' | 'checkpoint';
+export type SyncHealth = 'healthy' | 'stale' | 'backlogged' | 'conflicted' | 'unknown';
+export interface SyncObservation {
+    kind: ObservationKind;
+    at: number;
+    lagMs?: number;
+    queueSize?: number;
+}
+export interface SanitizedObservation {
+    kind: ObservationKind;
+    at: number;
+    lagMs: number;
+    queueSize: number;
+}
+export interface SyncMetrics {
+    health: SyncHealth;
+    observedAt: number;
+    lastActivityAt: number | null;
+    lagMs: number;
+    queueSize: number;
+    conflicts: number;
+    failures: number;
+    completed: number;
+}
+export interface DiagnosticExport {
+    format: 'lp-sync-diagnostics';
+    version: 1;
+    metrics: SyncMetrics;
+    observations: SanitizedObservation[];
+    truncated: boolean;
+}
+export interface SyncObservabilityOptions {
+    maxEvents?: number;
+    maxQueueSize?: number;
+    staleAfterMs?: number;
+}
+export declare class SyncObservabilityError extends Error {
+    readonly code: 'invalid' | 'capacity';
+    constructor(code: 'invalid' | 'capacity', message: string);
+}
+export interface SyncObservability {
+    record(observation: SyncObservation): void;
+    metrics(now?: number): SyncMetrics;
+    exportDiagnostics(now?: number): DiagnosticExport;
+}
+/** Keeps only allow-listed numeric sync signals; labels, payloads, and identifiers are never stored. */
+export declare function createSyncObservability(options?: SyncObservabilityOptions): SyncObservability;

package/dist/esm/index.js

@@ -0,0 +1,109 @@
+export class SyncObservabilityError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SyncObservabilityError';
+    }
+}
+const KINDS = [
+    'started',
+    'completed',
+    'failed',
+    'conflict',
+    'queue',
+    'checkpoint',
+];
+function boundedInteger(value, min, max, label) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min || value > max) {
+        throw new SyncObservabilityError('invalid', `${label} must be a safe integer from ${min} to ${max}.`);
+    }
+    return value;
+}
+function optionsRecord(value) {
+    if (typeof value !== 'object' ||
+        value === null ||
+        Array.isArray(value) ||
+        Object.getPrototypeOf(value) !== Object.prototype ||
+        Object.getOwnPropertySymbols(value).length !== 0) {
+        throw new SyncObservabilityError('invalid', 'Options and observations must be plain objects.');
+    }
+    return value;
+}
+/** Keeps only allow-listed numeric sync signals; labels, payloads, and identifiers are never stored. */
+export function createSyncObservability(options = {}) {
+    const rawOptions = optionsRecord(options);
+    if (Object.keys(rawOptions).some((key) => !['maxEvents', 'maxQueueSize', 'staleAfterMs'].includes(key))) {
+        throw new SyncObservabilityError('invalid', 'Options contain an unknown field.');
+    }
+    const maxEvents = boundedInteger(options.maxEvents ?? 200, 1, 10_000, 'maxEvents');
+    const maxQueueSize = boundedInteger(options.maxQueueSize ?? 10_000, 1, 1_000_000, 'maxQueueSize');
+    const staleAfterMs = boundedInteger(options.staleAfterMs ?? 60_000, 0, 86_400_000, 'staleAfterMs');
+    let observations = [];
+    let lagMs = 0;
+    let queueSize = 0;
+    let conflicts = 0;
+    let failures = 0;
+    let completed = 0;
+    let droppedEvents = false;
+    const metrics = (now = Date.now()) => {
+        const observedAt = boundedInteger(now, 0, Number.MAX_SAFE_INTEGER, 'now');
+        const lastActivityAt = observations.at(-1)?.at ?? null;
+        if (lastActivityAt !== null && observedAt < lastActivityAt)
+            throw new SyncObservabilityError('invalid', 'now predates the last observation.');
+        let health = 'unknown';
+        if (lastActivityAt !== null) {
+            health =
+                observedAt - lastActivityAt > staleAfterMs
+                    ? 'stale'
+                    : queueSize >= maxQueueSize
+                        ? 'backlogged'
+                        : conflicts > 0
+                            ? 'conflicted'
+                            : 'healthy';
+        }
+        return { health, observedAt, lastActivityAt, lagMs, queueSize, conflicts, failures, completed };
+    };
+    return {
+        record(input) {
+            const raw = optionsRecord(input);
+            if (Object.keys(raw).some((key) => !['kind', 'at', 'lagMs', 'queueSize'].includes(key))) {
+                throw new SyncObservabilityError('invalid', 'Observation contains an unknown field.');
+            }
+            if (typeof input.kind !== 'string' || !KINDS.includes(input.kind)) {
+                throw new SyncObservabilityError('invalid', 'Observation kind is not supported.');
+            }
+            const at = boundedInteger(input.at, 0, Number.MAX_SAFE_INTEGER, 'at');
+            const nextLag = boundedInteger(input.lagMs ?? 0, 0, Number.MAX_SAFE_INTEGER, 'lagMs');
+            const nextQueue = boundedInteger(input.queueSize ?? 0, 0, maxQueueSize, 'queueSize');
+            const previous = observations.at(-1);
+            if (previous && at < previous.at) {
+                throw new SyncObservabilityError('invalid', 'Observation timestamps must be nondecreasing.');
+            }
+            const safe = { kind: input.kind, at, lagMs: nextLag, queueSize: nextQueue };
+            observations.push(safe);
+            if (observations.length > maxEvents) {
+                observations = observations.slice(-maxEvents);
+                droppedEvents = true;
+            }
+            lagMs = nextLag;
+            queueSize = nextQueue;
+            if (input.kind === 'conflict')
+                conflicts++;
+            if (input.kind === 'failed')
+                failures++;
+            if (input.kind === 'completed')
+                completed++;
+        },
+        metrics,
+        exportDiagnostics(now = Date.now()) {
+            return {
+                format: 'lp-sync-diagnostics',
+                version: 1,
+                metrics: metrics(now),
+                observations: observations.map((entry) => ({ ...entry })),
+                truncated: droppedEvents,
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/sync-observability",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Bounded numeric synchronization metrics and payload-free diagnostics.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/check-types.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}