@memberjunction/integration-progress-artifacts 0.0.1 → 5.39.0

package/dist/IntegrationProgressEmitter.d.ts

@@ -0,0 +1,96 @@
+import type { IntegrationProgressEvent, IntegrationProgressEventType, IntegrationRunManifest } from './types.js';
+export interface EmitterOptions {
+    /** Root directory containing per-run subdirs. Defaults to ./logs/integration-runs. */
+    rootDir?: string;
+    /** Optional human-facing console mirror (default false — file is the primary record). */
+    consoleMirror?: boolean;
+}
+/**
+ * Side-channel hook invoked for EVERY emitted event. The server layer registers this once at
+ * startup to fan events onto a live GraphQL subscription topic (plan.md §11) WITHOUT this package
+ * depending on the server (inversion of control). The durable JSONL artifact + the pollable
+ * tail query remain the source of truth; this is the additive push path. Best-effort — a throwing
+ * hook never breaks the sync or the durable write.
+ */
+export type IntegrationProgressPublishHook = (manifest: IntegrationRunManifest, event: IntegrationProgressEvent) => void;
+/**
+ * Writes structured progress artifacts to `<rootDir>/<runID>/`:
+ * - manifest.json (written once at start)
+ * - progress.jsonl (append-only event stream; checkpoint events carry resumableState)
+ * - result.json (written once at terminate)
+ *
+ * Sequence numbers monotonic per emitter instance. Disk I/O is async and serialized
+ * via an internal promise chain — callers don't await; the emitter guarantees ordered
+ * writes. A flush() method awaits the queue when needed (test teardown, run completion).
+ */
+export declare class IntegrationProgressEmitter {
+    private readonly manifest;
+    private readonly runDir;
+    private readonly progressPath;
+    private readonly manifestPath;
+    private readonly resultPath;
+    private readonly consoleMirror;
+    private writeChain;
+    private seq;
+    private terminated;
+    private aggregateCounts;
+    private errors;
+    private warnings;
+    private latestCheckpointSeq?;
+    private readonly startMs;
+    private static _publishHook?;
+    /**
+     * Register (or clear, with no arg) the global publish hook. The server registers this at startup
+     * so every emitted event also fans out to the live GraphQL subscription, in addition to the
+     * durable JSONL artifact + the pollable tail query.
+     */
+    static SetPublishHook(hook?: IntegrationProgressPublishHook): void;
+    constructor(manifest: IntegrationRunManifest, opts?: EmitterOptions);
+    /** Emit a generic event. */
+    emit(eventType: IntegrationProgressEventType, partial?: Partial<Omit<IntegrationProgressEvent, 'ts' | 'seq' | 'eventType'>>): void;
+    /** Convenience helpers — sugared `emit()` for the common cases. */
+    runStart(message?: string): void;
+    stageStart(stage: string, message?: string): void;
+    stageComplete(stage: string, counts?: IntegrationProgressEvent['counts']): void;
+    stageError(stage: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Emit a non-fatal warning. Carries a structured {stage, code, message, data}
+     * payload that the reader aggregates into the run result's `warnings[]` rollup.
+     * Unlike `stageError`, a warning never fails the run.
+     */
+    warning(stage: string, code: string, message: string, data?: Record<string, unknown>): void;
+    heartbeat(stage: string, message: string, counts?: IntegrationProgressEvent['counts']): void;
+    /**
+     * Write a resumable checkpoint. resumableState should carry enough subsystem-
+     * specific data for the originating service to resume from this point.
+     */
+    checkpoint(stage: string, resumableState: Record<string, unknown>): void;
+    externalCallStart(url: string, method: string, data?: Record<string, unknown>): void;
+    externalCallComplete(url: string, method: string, status: number, durationMs: number): void;
+    objectAdded(objectName: string, source: 'Declared' | 'Discovered' | 'Custom'): void;
+    fieldAdded(objectName: string, fieldName: string, source: 'Declared' | 'Discovered' | 'Custom'): void;
+    pkClassifierInvoked(objectName: string): void;
+    pkClassifierResult(objectName: string, verdict: Record<string, unknown>): void;
+    entityGenerated(objectName: string, mjEntityName: string): void;
+    entitySkippedNoPK(objectName: string): void;
+    /** Terminate the run as success. */
+    complete(message?: string): Promise<void>;
+    /** Terminate the run as failure. */
+    fail(message: string, code?: string): Promise<void>;
+    /**
+     * Terminate the run as CANCELLED (a user/system abort stopped it mid-flight, not a failure and not a
+     * clean completion). Emits exitReason='aborted' so a cancelled run is distinguishable from one that
+     * finished — the persisted CompanyIntegrationRun has no 'Cancelled' status, so the artifact's
+     * ExitReason is the GQL-visible signal that the run was stopped early (partial state is still durable).
+     */
+    cancel(message?: string): Promise<void>;
+    /** Await all pending writes. */
+    flush(): Promise<void>;
+    private bootstrap;
+    private writeTerminal;
+    /** Reconstruct a {@link SyncWarning} from an emitted `'warning'` event. */
+    private warningFromEvent;
+    private mirrorToConsole;
+    static newRunID(prefix?: string): string;
+}
+//# sourceMappingURL=IntegrationProgressEmitter.d.ts.map

package/dist/IntegrationProgressEmitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntegrationProgressEmitter.d.ts","sourceRoot":"","sources":["../src/IntegrationProgressEmitter.ts"],"names":[],"mappings":"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"}

package/dist/IntegrationProgressEmitter.js

@@ -0,0 +1,249 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { CountsContributeToAggregate } from './types.js';
+/**
+ * Writes structured progress artifacts to `<rootDir>/<runID>/`:
+ * - manifest.json (written once at start)
+ * - progress.jsonl (append-only event stream; checkpoint events carry resumableState)
+ * - result.json (written once at terminate)
+ *
+ * Sequence numbers monotonic per emitter instance. Disk I/O is async and serialized
+ * via an internal promise chain — callers don't await; the emitter guarantees ordered
+ * writes. A flush() method awaits the queue when needed (test teardown, run completion).
+ */
+export class IntegrationProgressEmitter {
+    /**
+     * Register (or clear, with no arg) the global publish hook. The server registers this at startup
+     * so every emitted event also fans out to the live GraphQL subscription, in addition to the
+     * durable JSONL artifact + the pollable tail query.
+     */
+    static SetPublishHook(hook) {
+        IntegrationProgressEmitter._publishHook = hook;
+    }
+    constructor(manifest, opts = {}) {
+        this.manifest = manifest;
+        this.writeChain = Promise.resolve();
+        this.seq = 0;
+        this.terminated = false;
+        this.aggregateCounts = { processed: 0, succeeded: 0, failed: 0, skipped: 0 };
+        this.errors = [];
+        this.warnings = [];
+        this.startMs = Date.now();
+        const root = opts.rootDir ?? join(process.cwd(), 'logs', 'integration-runs');
+        this.runDir = join(root, this.manifest.runID);
+        this.progressPath = join(this.runDir, 'progress.jsonl');
+        this.manifestPath = join(this.runDir, 'manifest.json');
+        this.resultPath = join(this.runDir, 'result.json');
+        this.consoleMirror = opts.consoleMirror ?? false;
+        this.writeChain = this.bootstrap();
+    }
+    /** Emit a generic event. */
+    emit(eventType, partial = {}) {
+        if (this.terminated)
+            return;
+        const event = {
+            ts: new Date().toISOString(),
+            seq: ++this.seq,
+            eventType,
+            ...partial,
+        };
+        if (eventType === 'checkpoint')
+            this.latestCheckpointSeq = event.seq;
+        // Count accumulation — applied vs. fetched distinction (see counts shape in types.ts).
+        // `stage.complete` (and the terminal `run.complete`) carry the authoritative APPLIED
+        // quartet {processed,succeeded,failed,skipped} for a finished stage/run. By contrast,
+        // `records.batch.complete` carries a FETCHED `processed` count for live per-batch
+        // progress only — the SAME records are later reported again, applied, in `stage.complete`.
+        // Summing both double-counts every record (a 56-record sync would report 112). So only
+        // the applied-rollup events feed the run-level aggregate; batch/heartbeat counts stay in
+        // the stream for progress bars but are NOT summed here.
+        if (partial.counts && CountsContributeToAggregate(eventType)) {
+            this.aggregateCounts.processed += partial.counts.processed ?? 0;
+            this.aggregateCounts.succeeded += partial.counts.succeeded ?? 0;
+            this.aggregateCounts.failed += partial.counts.failed ?? 0;
+            this.aggregateCounts.skipped += partial.counts.skipped ?? 0;
+        }
+        if (eventType === 'stage.error' || eventType === 'record.error' || eventType === 'run.fail') {
+            const code = typeof event.data?.code === 'string' ? event.data.code : undefined;
+            this.errors.push({
+                stage: event.stage,
+                message: event.message ?? `${eventType} (no message)`,
+                code,
+            });
+        }
+        if (eventType === 'warning') {
+            this.warnings.push(this.warningFromEvent(event));
+        }
+        const line = JSON.stringify(event) + '\n';
+        if (this.consoleMirror) {
+            this.mirrorToConsole(event);
+        }
+        // §11 push path: fan out to the live subscription via the registered hook. Best-effort —
+        // never breaks the sync or the durable write (which remain the source of truth).
+        const hook = IntegrationProgressEmitter._publishHook;
+        if (hook) {
+            try {
+                hook(this.manifest, event);
+            }
+            catch { /* publish is best-effort */ }
+        }
+        this.writeChain = this.writeChain.then(() => fs.appendFile(this.progressPath, line, 'utf-8'));
+    }
+    /** Convenience helpers — sugared `emit()` for the common cases. */
+    runStart(message) {
+        this.emit('run.start', { message, level: 'info' });
+    }
+    stageStart(stage, message) {
+        this.emit('stage.start', { stage, message, level: 'info' });
+    }
+    stageComplete(stage, counts) {
+        this.emit('stage.complete', { stage, counts, level: 'info' });
+    }
+    stageError(stage, message, data) {
+        this.emit('stage.error', { stage, message, level: 'error', data });
+    }
+    /**
+     * Emit a non-fatal warning. Carries a structured {stage, code, message, data}
+     * payload that the reader aggregates into the run result's `warnings[]` rollup.
+     * Unlike `stageError`, a warning never fails the run.
+     */
+    warning(stage, code, message, data) {
+        this.emit('warning', {
+            stage,
+            message,
+            level: 'warn',
+            data: { code, ...(data ?? {}) },
+        });
+    }
+    heartbeat(stage, message, counts) {
+        this.emit('progress.heartbeat', { stage, message, counts, level: 'info' });
+    }
+    /**
+     * Write a resumable checkpoint. resumableState should carry enough subsystem-
+     * specific data for the originating service to resume from this point.
+     */
+    checkpoint(stage, resumableState) {
+        this.emit('checkpoint', { stage, resumableState, level: 'debug' });
+    }
+    externalCallStart(url, method, data) {
+        this.emit('external.call.start', { data: { url, method, ...(data ?? {}) }, level: 'debug' });
+    }
+    externalCallComplete(url, method, status, durationMs) {
+        this.emit('external.call.complete', {
+            data: { url, method, status, durationMs },
+            level: status >= 400 ? 'warn' : 'debug',
+        });
+    }
+    objectAdded(objectName, source) {
+        this.emit('discovery.object.added', { data: { objectName, source }, level: 'info' });
+    }
+    fieldAdded(objectName, fieldName, source) {
+        this.emit('discovery.field.added', { data: { objectName, fieldName, source }, level: 'debug' });
+    }
+    pkClassifierInvoked(objectName) {
+        this.emit('pk.classifier.invoked', { data: { objectName }, level: 'info' });
+    }
+    pkClassifierResult(objectName, verdict) {
+        this.emit('pk.classifier.result', { data: { objectName, ...verdict }, level: 'info' });
+    }
+    entityGenerated(objectName, mjEntityName) {
+        this.emit('entity.generated', { data: { objectName, mjEntityName }, level: 'info' });
+    }
+    entitySkippedNoPK(objectName) {
+        this.emit('entity.skipped-no-pk', { data: { objectName }, level: 'warn' });
+    }
+    /** Terminate the run as success. */
+    async complete(message) {
+        if (this.terminated)
+            return;
+        this.emit('run.complete', { message, level: 'info' });
+        await this.writeTerminal({
+            success: true,
+            exitReason: 'completed',
+        });
+    }
+    /** Terminate the run as failure. */
+    async fail(message, code) {
+        if (this.terminated)
+            return;
+        this.emit('run.fail', { message, level: 'error', data: code ? { code } : undefined });
+        await this.writeTerminal({
+            success: false,
+            exitReason: code === 'budget-exhausted' ? 'budget-exhausted' : 'failed',
+        });
+    }
+    /**
+     * Terminate the run as CANCELLED (a user/system abort stopped it mid-flight, not a failure and not a
+     * clean completion). Emits exitReason='aborted' so a cancelled run is distinguishable from one that
+     * finished — the persisted CompanyIntegrationRun has no 'Cancelled' status, so the artifact's
+     * ExitReason is the GQL-visible signal that the run was stopped early (partial state is still durable).
+     */
+    async cancel(message) {
+        if (this.terminated)
+            return;
+        this.emit('run.cancel', { message: message ?? 'Sync cancelled by user', level: 'warn' });
+        await this.writeTerminal({
+            success: false,
+            exitReason: 'aborted',
+        });
+    }
+    /** Await all pending writes. */
+    async flush() {
+        await this.writeChain;
+    }
+    // ── Internals ──────────────────────────────────────────────────────
+    async bootstrap() {
+        await fs.mkdir(this.runDir, { recursive: true });
+        await fs.writeFile(this.manifestPath, JSON.stringify(this.manifest, null, 2), 'utf-8');
+    }
+    async writeTerminal(partial) {
+        this.terminated = true;
+        await this.writeChain;
+        const result = {
+            runID: this.manifest.runID,
+            completedAt: new Date().toISOString(),
+            success: partial.success,
+            exitReason: partial.exitReason,
+            durationMs: Date.now() - this.startMs,
+            aggregateCounts: this.aggregateCounts,
+            errors: this.errors.length > 0 ? this.errors : undefined,
+            warnings: this.warnings.length > 0 ? this.warnings : undefined,
+            warningCount: this.warnings.length,
+            resumableFromSeq: this.latestCheckpointSeq,
+        };
+        await fs.writeFile(this.resultPath, JSON.stringify(result, null, 2), 'utf-8');
+    }
+    /** Reconstruct a {@link SyncWarning} from an emitted `'warning'` event. */
+    warningFromEvent(event) {
+        const { code, ...rest } = event.data ?? {};
+        return {
+            code: typeof code === 'string' ? code : 'UNKNOWN',
+            stage: event.stage ?? '',
+            message: event.message ?? '',
+            data: Object.keys(rest).length > 0 ? rest : undefined,
+        };
+    }
+    mirrorToConsole(event) {
+        const level = event.level ?? 'info';
+        const tag = `[${event.eventType}]${event.stage ? ` [${event.stage}]` : ''}`;
+        const msg = event.message ?? '';
+        switch (level) {
+            case 'error':
+                console.error(tag, msg);
+                break;
+            case 'warn':
+                console.warn(tag, msg);
+                break;
+            case 'debug':
+                console.debug(tag, msg);
+                break;
+            default: console.log(tag, msg);
+        }
+    }
+    static newRunID(prefix) {
+        const hi = Math.floor(Math.random() * 0xffffffff).toString(16).padStart(8, '0');
+        const lo = Math.floor(Math.random() * 0xffffffff).toString(16).padStart(8, '0');
+        return `${prefix ?? 'run'}-${Date.now()}-${hi}${lo}`;
+    }
+}
+//# sourceMappingURL=IntegrationProgressEmitter.js.map

package/dist/IntegrationProgressEmitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntegrationProgressEmitter.js","sourceRoot":"","sources":["../src/IntegrationProgressEmitter.ts"],"names":[],"mappings":"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"}

package/dist/IntegrationProgressReader.d.ts

@@ -0,0 +1,33 @@
+import type { IntegrationProgressEvent, IntegrationRunFilter, IntegrationRunSnapshot } from './types.js';
+/**
+ * Read API for the progress artifacts. Frontend / health-check / resumption code
+ * uses this to inspect ongoing or completed runs without touching the emitter.
+ *
+ * Implementation is purely file-system reads; no shared state with the emitter
+ * (an emitter in another process can write while this reader tails).
+ */
+export declare class IntegrationProgressReader {
+    private readonly rootDir;
+    constructor(rootDir?: string);
+    /** List runs, newest-first by mtime. */
+    ListRuns(filter?: IntegrationRunFilter, limit?: number): Promise<IntegrationRunSnapshot[]>;
+    /** Read snapshot of a single run. Returns undefined if runID not found. */
+    GetRun(runID: string): Promise<IntegrationRunSnapshot | undefined>;
+    /** Tail events since a given sequence. */
+    Tail(runID: string, sinceSeq?: number): Promise<IntegrationProgressEvent[]>;
+    /** Find the latest checkpoint for a run (for resumption). */
+    LatestCheckpoint(runID: string): Promise<IntegrationProgressEvent | undefined>;
+    /** Find all in-flight (non-terminated) runs — for restart-resumption discovery. */
+    FindInFlight(): Promise<IntegrationRunSnapshot[]>;
+    private safeReadDir;
+    private safeReadFile;
+    private safeReadJSON;
+    private runMtime;
+    private readProgressTail;
+    private countLines;
+    private aggregateCountsFromTail;
+    private aggregateWarningsFromTail;
+    /** Reconstruct a {@link SyncWarning} from a persisted `'warning'` event. */
+    private warningFromEvent;
+}
+//# sourceMappingURL=IntegrationProgressReader.d.ts.map

package/dist/IntegrationProgressReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntegrationProgressReader.d.ts","sourceRoot":"","sources":["../src/IntegrationProgressReader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACR,wBAAwB,EACxB,oBAAoB,EAGpB,sBAAsB,EAEzB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,qBAAa,yBAAyB;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,GAAE,MAAwD;IAE9F,wCAAwC;IAC3B,QAAQ,CAAC,MAAM,GAAE,oBAAyB,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IAkBvG,2EAA2E;IAC9D,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC;IAsB/E,0CAA0C;IAC7B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,OAAO,CAAC,wBAAwB,EAAE,CAAC;IAenF,6DAA6D;IAChD,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC;IAQ3F,mFAAmF;IACtE,YAAY,IAAI,OAAO,CAAC,sBAAsB,EAAE,CAAC;YAMhD,WAAW;YAGX,YAAY;YAGZ,YAAY;YAKZ,QAAQ;YAMR,gBAAgB;YAWhB,UAAU;YAKV,uBAAuB;YAuBvB,yBAAyB;IAcvC,4EAA4E;IAC5E,OAAO,CAAC,gBAAgB;CAS3B"}

package/dist/IntegrationProgressReader.js

@@ -0,0 +1,209 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { CountsContributeToAggregate } from './types.js';
+/**
+ * Read API for the progress artifacts. Frontend / health-check / resumption code
+ * uses this to inspect ongoing or completed runs without touching the emitter.
+ *
+ * Implementation is purely file-system reads; no shared state with the emitter
+ * (an emitter in another process can write while this reader tails).
+ */
+export class IntegrationProgressReader {
+    constructor(rootDir = join(process.cwd(), 'logs', 'integration-runs')) {
+        this.rootDir = rootDir;
+    }
+    /** List runs, newest-first by mtime. */
+    async ListRuns(filter = {}, limit = 50) {
+        const entries = await this.safeReadDir(this.rootDir);
+        const snapshots = [];
+        for (const runID of entries) {
+            const snap = await this.GetRun(runID);
+            if (!snap)
+                continue;
+            if (filter.runKind && snap.manifest.runKind !== filter.runKind)
+                continue;
+            if (filter.integrationID && snap.manifest.integrationID !== filter.integrationID)
+                continue;
+            if (filter.companyIntegrationID && snap.manifest.companyIntegrationID !== filter.companyIntegrationID)
+                continue;
+            if (filter.sinceTs && snap.manifest.startedAt < filter.sinceTs)
+                continue;
+            if (filter.inFlightOnly && !snap.isInFlight)
+                continue;
+            const mtime = await this.runMtime(runID);
+            snapshots.push({ snap, mtimeMs: mtime });
+        }
+        snapshots.sort((a, b) => b.mtimeMs - a.mtimeMs);
+        return snapshots.slice(0, limit).map(s => s.snap);
+    }
+    /** Read snapshot of a single run. Returns undefined if runID not found. */
+    async GetRun(runID) {
+        const runDir = join(this.rootDir, runID);
+        const manifest = await this.safeReadJSON(join(runDir, 'manifest.json'));
+        if (!manifest)
+            return undefined;
+        const result = await this.safeReadJSON(join(runDir, 'result.json'));
+        const events = await this.readProgressTail(join(runDir, 'progress.jsonl'), 1);
+        const latestEvent = events[events.length - 1];
+        const allCounts = await this.aggregateCountsFromTail(join(runDir, 'progress.jsonl'));
+        const warnings = await this.aggregateWarningsFromTail(join(runDir, 'progress.jsonl'));
+        const eventCount = await this.countLines(join(runDir, 'progress.jsonl'));
+        return {
+            manifest,
+            latestEvent,
+            eventCount,
+            result,
+            isInFlight: !result,
+            counts: allCounts,
+            warnings: warnings.length > 0 ? warnings : undefined,
+            warningCount: warnings.length,
+        };
+    }
+    /** Tail events since a given sequence. */
+    async Tail(runID, sinceSeq = 0) {
+        const path = join(this.rootDir, runID, 'progress.jsonl');
+        const raw = await this.safeReadFile(path);
+        if (!raw)
+            return [];
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const ev = JSON.parse(line);
+                if (ev.seq > sinceSeq)
+                    out.push(ev);
+            }
+            catch { /* skip malformed line */ }
+        }
+        return out;
+    }
+    /** Find the latest checkpoint for a run (for resumption). */
+    async LatestCheckpoint(runID) {
+        const events = await this.Tail(runID, 0);
+        for (let i = events.length - 1; i >= 0; i--) {
+            if (events[i].eventType === 'checkpoint')
+                return events[i];
+        }
+        return undefined;
+    }
+    /** Find all in-flight (non-terminated) runs — for restart-resumption discovery. */
+    async FindInFlight() {
+        return this.ListRuns({ inFlightOnly: true }, 1000);
+    }
+    // ── Internals ──────────────────────────────────────────────────────
+    async safeReadDir(p) {
+        try {
+            return await fs.readdir(p);
+        }
+        catch {
+            return [];
+        }
+    }
+    async safeReadFile(p) {
+        try {
+            return await fs.readFile(p, 'utf-8');
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async safeReadJSON(p) {
+        const raw = await this.safeReadFile(p);
+        if (!raw)
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async runMtime(runID) {
+        try {
+            const s = await fs.stat(join(this.rootDir, runID));
+            return s.mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+    }
+    async readProgressTail(path, maxLines) {
+        const raw = await this.safeReadFile(path);
+        if (!raw)
+            return [];
+        const lines = raw.split('\n').filter(Boolean);
+        const tail = lines.slice(Math.max(0, lines.length - maxLines));
+        const out = [];
+        for (const line of tail) {
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* skip */ }
+        }
+        return out;
+    }
+    async countLines(path) {
+        const raw = await this.safeReadFile(path);
+        if (!raw)
+            return 0;
+        return raw.split('\n').filter(Boolean).length;
+    }
+    async aggregateCountsFromTail(path) {
+        const raw = await this.safeReadFile(path);
+        if (!raw)
+            return undefined;
+        const totals = { processed: 0, succeeded: 0, failed: 0, skipped: 0 };
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const ev = JSON.parse(line);
+                if (!ev.counts)
+                    continue;
+                // Mirror the emitter's rule (CountsContributeToAggregate): only the APPLIED
+                // rollup events (`stage.complete`/`run.complete`) feed the total. The FETCHED
+                // `processed` on `records.batch.complete` is per-batch progress only and would
+                // double-count every record if summed here. Keeping the rule in one place
+                // guarantees a re-derived count matches the emitter's running aggregate.
+                if (!CountsContributeToAggregate(ev.eventType))
+                    continue;
+                totals.processed += ev.counts.processed ?? 0;
+                totals.succeeded += ev.counts.succeeded ?? 0;
+                totals.failed += ev.counts.failed ?? 0;
+                totals.skipped += ev.counts.skipped ?? 0;
+            }
+            catch { /* skip */ }
+        }
+        return totals;
+    }
+    async aggregateWarningsFromTail(path) {
+        const raw = await this.safeReadFile(path);
+        if (!raw)
+            return [];
+        const warnings = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const ev = JSON.parse(line);
+                if (ev.eventType !== 'warning')
+                    continue;
+                warnings.push(this.warningFromEvent(ev));
+            }
+            catch { /* skip */ }
+        }
+        return warnings;
+    }
+    /** Reconstruct a {@link SyncWarning} from a persisted `'warning'` event. */
+    warningFromEvent(event) {
+        const { code, ...rest } = event.data ?? {};
+        return {
+            code: typeof code === 'string' ? code : 'UNKNOWN',
+            stage: event.stage ?? '',
+            message: event.message ?? '',
+            data: Object.keys(rest).length > 0 ? rest : undefined,
+        };
+    }
+}
+//# sourceMappingURL=IntegrationProgressReader.js.map

package/dist/IntegrationProgressReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntegrationProgressReader.js","sourceRoot":"","sources":["../src/IntegrationProgressReader.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { IntegrationProgressEmitter } from './IntegrationProgressEmitter.js';
+export type { EmitterOptions } from './IntegrationProgressEmitter.js';
+export { IntegrationProgressReader } from './IntegrationProgressReader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export { IntegrationProgressEmitter } from './IntegrationProgressEmitter.js';
+export { IntegrationProgressReader } from './IntegrationProgressReader.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAE7E,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Structured progress event types — generic enough to cover RSU runs, sync runs,
+ * connector-creation pipelines, table creation. The vocabulary is fixed; specific
+ * subsystems carry their own state shape in the `data` field.
+ */
+/** What kind of run produced this progress stream. */
+export type IntegrationRunKind = 'SyncRun' | 'ConnectorCreation' | 'RSU' | 'TableCreation' | 'Discovery' | 'Enrichment' | 'Other';
+/** Event types in the progress.jsonl stream. */
+export type IntegrationProgressEventType = 
+/** Run started. */
+'run.start'
+/** Run terminated successfully. */
+ | 'run.complete'
+/** Run terminated with failure. */
+ | 'run.fail'
+/** Run cancelled mid-flight by a user/system abort (not a failure, not a clean completion). */
+ | 'run.cancel'
+/** Run resumed from a prior checkpoint after a kill/restart. */
+ | 'run.resumed'
+/** A named stage within the run started. */
+ | 'stage.start'
+/** A named stage within the run completed. */
+ | 'stage.complete'
+/** A named stage within the run errored (run may continue or fail). */
+ | 'stage.error'
+/** A batch of records is about to be processed (sync paths). */
+ | 'records.batch.start'
+/** A batch of records has been processed. */
+ | 'records.batch.complete'
+/** A single record errored within a batch. */
+ | 'record.error'
+/**
+ * A non-fatal warning surfaced during the run. Carries a structured
+ * {stage, code, message, data} payload (see {@link SyncWarning}). Distinct
+ * from `stage.error`/`record.error`: a warning never fails the run, it is
+ * aggregated separately into the result's `warnings[]` rollup.
+ */
+ | 'warning'
+/** Long-running progress with no record-level granularity. */
+ | 'progress.heartbeat'
+/**
+ * Resumable checkpoint. Carries `resumableState` — the subsystem-specific
+ * shape needed for the run to resume from this exact point. On restart,
+ * the resumption engine reads the latest checkpoint event for any in-flight
+ * run and hands the resumableState back to the originating service.
+ */
+ | 'checkpoint'
+/** An outbound API call started (vendor-API debugging, esp. GraphQL). */
+ | 'external.call.start'
+/** An outbound API call completed. */
+ | 'external.call.complete'
+/** An outbound API call retrying after transient failure. */
+ | 'external.call.retry'
+/** TransformRecord (or equivalent) reshaped a record. */
+ | 'transform.applied'
+/** Discovery added a new IntegrationObject row. */
+ | 'discovery.object.added'
+/** Discovery added a new IntegrationObjectField row. */
+ | 'discovery.field.added'
+/** PK classifier invoked for an object. */
+ | 'pk.classifier.invoked'
+/** PK classifier returned a verdict. */
+ | 'pk.classifier.result'
+/** An MJ entity was generated for an IO row that has a PK. */
+ | 'entity.generated'
+/** An IO row was skipped from entity generation because it lacks a PK. */
+ | 'entity.skipped-no-pk';
+/** Severity levels for progress events. */
+export type IntegrationProgressLevel = 'info' | 'warn' | 'error' | 'debug';
+/**
+ * Whether an event's `counts` feed the run-level APPLIED aggregate
+ * ({@link IntegrationRunResult.aggregateCounts} / {@link IntegrationRunSnapshot.counts}).
+ *
+ * Two count vocabularies flow through the stream and must NOT both be summed:
+ * - `stage.complete` / `run.complete` carry the authoritative **applied** quartet
+ *   {processed,succeeded,failed,skipped} for a finished stage/run → these aggregate.
+ * - `records.batch.complete` (and `progress.heartbeat`) carry a *fetched* / in-flight
+ *   `processed` count for live per-batch progress only. The same records are reported
+ *   again — applied — by the stage rollup, so summing batch counts double-counts every
+ *   record (a 56-record sync would report processed:112). These do NOT aggregate.
+ *
+ * The emitter and the reader both call this so a re-derived count always matches the
+ * emitter's running aggregate. Centralizing the rule here keeps the two in lock-step.
+ */
+export declare function CountsContributeToAggregate(eventType: IntegrationProgressEventType): boolean;
+/**
+ * A structured, non-fatal warning surfaced during an integration run. Emitted via
+ * `IntegrationProgressEmitter.warning(...)` as a `'warning'` event and aggregated by
+ * the reader into the run result's `warnings[]` rollup (with a `warningCount`).
+ * Unlike errors, warnings never fail the run.
+ */
+export interface SyncWarning {
+    /** Stable, machine-matchable warning code (e.g. 'FIELD_TRUNCATED'). */
+    code: string;
+    /** The stage that produced the warning. */
+    stage: string;
+    /** Human-readable warning message. */
+    message: string;
+    /** Optional subsystem-specific structured payload. */
+    data?: Record<string, unknown>;
+}
+/** A single event in the progress.jsonl stream (one line, JSON-encoded). */
+export interface IntegrationProgressEvent {
+    /** ISO 8601 timestamp. */
+    ts: string;
+    /** Sequence number within the run (monotonic). */
+    seq: number;
+    /** Event type. */
+    eventType: IntegrationProgressEventType;
+    /** Severity (default 'info'). */
+    level?: IntegrationProgressLevel;
+    /** Stage name (when applicable). */
+    stage?: string;
+    /** Free-form human message (optional — UI may format from data instead). */
+    message?: string;
+    /** Counts snapshot — convenient for UI summary without parsing data. */
+    counts?: {
+        processed?: number;
+        succeeded?: number;
+        failed?: number;
+        skipped?: number;
+        totalKnown?: number;
+    };
+    /**
+     * Resumable state — only on `checkpoint` events.
+     * Subsystem-specific shape: sync uses {watermark, lastRecordID, batchIndex, pageCursor},
+     * pipelines use {currentStep, stageInputs}, etc. The originating service
+     * interprets the shape based on `stage`.
+     */
+    resumableState?: Record<string, unknown>;
+    /** Subsystem-specific structured payload. */
+    data?: Record<string, unknown>;
+}
+/** manifest.json — written once at run start. */
+export interface IntegrationRunManifest {
+    runID: string;
+    runKind: IntegrationRunKind;
+    integrationID?: string;
+    companyIntegrationID?: string;
+    objectName?: string;
+    triggerType?: 'Manual' | 'Scheduled' | 'Webhook' | 'Pipeline' | 'Restart';
+    startedAt: string;
+    expectedStages?: string[];
+    /** Free-form context (vendor name, RSU mode, etc.). */
+    context?: Record<string, unknown>;
+}
+/** result.json — written once at run end (success or failure). */
+export interface IntegrationRunResult {
+    runID: string;
+    completedAt: string;
+    success: boolean;
+    exitReason: 'completed' | 'failed' | 'killed' | 'budget-exhausted' | 'aborted';
+    durationMs: number;
+    aggregateCounts?: {
+        processed: number;
+        succeeded: number;
+        failed: number;
+        skipped: number;
+    };
+    errors?: Array<{
+        stage?: string;
+        message: string;
+        code?: string;
+    }>;
+    /** Non-fatal warnings surfaced during the run (rollup of `'warning'` events). */
+    warnings?: SyncWarning[];
+    /** Total number of `'warning'` events emitted (length of `warnings`). */
+    warningCount?: number;
+    /** When non-empty, this run is resumable: latest checkpoint event sequence. */
+    resumableFromSeq?: number;
+}
+/** Snapshot returned by the reader API for a single run. */
+export interface IntegrationRunSnapshot {
+    manifest: IntegrationRunManifest;
+    latestEvent?: IntegrationProgressEvent;
+    eventCount: number;
+    result?: IntegrationRunResult;
+    isInFlight: boolean;
+    /** Latest counts derived from the event stream. */
+    counts?: NonNullable<IntegrationProgressEvent['counts']>;
+    /** Non-fatal warnings derived from the `'warning'` events in the stream. */
+    warnings?: SyncWarning[];
+    /** Total number of `'warning'` events in the stream (length of `warnings`). */
+    warningCount?: number;
+}
+/** Filter shape for the reader's ListRuns API. */
+export interface IntegrationRunFilter {
+    runKind?: IntegrationRunKind;
+    integrationID?: string;
+    companyIntegrationID?: string;
+    sinceTs?: string;
+    inFlightOnly?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,24 @@
+/**
+ * Structured progress event types — generic enough to cover RSU runs, sync runs,
+ * connector-creation pipelines, table creation. The vocabulary is fixed; specific
+ * subsystems carry their own state shape in the `data` field.
+ */
+/**
+ * Whether an event's `counts` feed the run-level APPLIED aggregate
+ * ({@link IntegrationRunResult.aggregateCounts} / {@link IntegrationRunSnapshot.counts}).
+ *
+ * Two count vocabularies flow through the stream and must NOT both be summed:
+ * - `stage.complete` / `run.complete` carry the authoritative **applied** quartet
+ *   {processed,succeeded,failed,skipped} for a finished stage/run → these aggregate.
+ * - `records.batch.complete` (and `progress.heartbeat`) carry a *fetched* / in-flight
+ *   `processed` count for live per-batch progress only. The same records are reported
+ *   again — applied — by the stage rollup, so summing batch counts double-counts every
+ *   record (a 56-record sync would report processed:112). These do NOT aggregate.
+ *
+ * The emitter and the reader both call this so a re-derived count always matches the
+ * emitter's running aggregate. Centralizing the rule here keeps the two in lock-step.
+ */
+export function CountsContributeToAggregate(eventType) {
+    return eventType === 'stage.complete' || eventType === 'run.complete';
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4EH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,2BAA2B,CAAC,SAAuC;IAC/E,OAAO,SAAS,KAAK,gBAAgB,IAAI,SAAS,KAAK,cAAc,CAAC;AAC1E,CAAC"}

package/package.json

@@ -1,10 +1,32 @@
 {
   "name": "@memberjunction/integration-progress-artifacts",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/integration-progress-artifacts",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "type": "module",
+  "version": "5.39.0",
+  "description": "Structured progress artifacts for integration runs: manifest.json + progress.jsonl (append-only with resumable checkpoints) + result.json. Generic across RSU runs, sync runs, creation pipelines, table creation. Replaces ad-hoc console.log with file-system-durable progress that survives transient failures + server restarts.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@memberjunction/global": "5.39.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "tsc-alias": "^1.8.16",
+    "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  },
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/README.md

@@ -1,45 +0,0 @@
-# @memberjunction/integration-progress-artifacts
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/integration-progress-artifacts`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**