@flowdot.ai/guardian-agent 0.1.0

package/dist/audit/writer.js

@@ -0,0 +1,263 @@
+/**
+ * Single-writer append-only JSONL audit log with hash chain. SPEC §2.
+ */
+import { open } from 'node:fs/promises';
+import { readFileSync, existsSync } from 'node:fs';
+import { ulid } from 'ulidx';
+import { SPEC_VERSION } from '../types.js';
+import { GENESIS_HASH, computeRecordHash, canonicalJsonStringify } from './chain.js';
+import { signRecord } from './signature.js';
+import { payloadFromRecord } from './attestor.js';
+/**
+ * Append-only writer. Internal queue ensures the hash chain is strictly
+ * ordered even when callers `append` concurrently.
+ */
+export class AuditLogWriter {
+    path;
+    agentId;
+    sessionId;
+    fileMode;
+    handle = null;
+    openPromise = null;
+    closed = false;
+    _tipHash = GENESIS_HASH;
+    queue = Promise.resolve();
+    signWith;
+    onTipRecovered;
+    attestor;
+    attestEvery;
+    attestOnClose;
+    // Running count of records appended in THIS process. Reset to 0 on open()
+    // and incremented on each writeOne. Used to fire attestation at fixed
+    // intervals.
+    appendedCount = 0;
+    // Set true while emitting an attestation-related audit row, so the
+    // attestation hook does NOT re-trigger on its own audit rows. Prevents
+    // unbounded recursion: an attestation row would otherwise be the next
+    // record to attest.
+    attestationInFlight = false;
+    constructor(options) {
+        this.path = options.path;
+        this.agentId = options.agentId;
+        this.sessionId = options.sessionId;
+        this.fileMode = options.fileMode ?? 0o600;
+        this.signWith = options.signWith;
+        this.onTipRecovered = options.onTipRecovered;
+        this.attestor = options.attestor;
+        this.attestEvery = options.attestEvery ?? 100;
+        this.attestOnClose = options.attestOnClose ?? true;
+        if (this.attestEvery <= 0) {
+            throw new Error('attestEvery must be > 0');
+        }
+    }
+    /** Tip of the hash chain (the last appended record's hash). */
+    get tipHash() {
+        return this._tipHash;
+    }
+    /** Open the underlying file (idempotent + single-flight). Recovers tip hash if file exists. */
+    async open() {
+        if (this.openPromise)
+            return this.openPromise;
+        this.openPromise = (async () => {
+            let recoveredTip = null;
+            if (existsSync(this.path)) {
+                const recovered = await this.recoverTipRecord();
+                if (recovered !== null) {
+                    this._tipHash = computeRecordHash(recovered);
+                    recoveredTip = recovered;
+                }
+            }
+            // Open for append; create if absent. Mode applies on creation only.
+            this.handle = await open(this.path, 'a', this.fileMode);
+            // Fire the recovery callback AFTER the handle is open so the callback
+            // can use append() if it wants to record a session_recovered event.
+            if (recoveredTip !== null && this.onTipRecovered) {
+                await this.onTipRecovered(recoveredTip);
+            }
+        })();
+        return this.openPromise;
+    }
+    /** Append a record. Computes hash chain; serializes via internal queue. */
+    async append(input) {
+        if (this.closed) {
+            throw new Error('AuditLogWriter is closed');
+        }
+        // Serialize via the queue: each append waits on the previous one. We chain
+        // the open() into the queue so concurrent first-appends do not race.
+        const result = this.queue.then(async () => {
+            await this.open();
+            return this.writeOne(input);
+        });
+        // Replace the queue with a swallowed-error version so one failure doesn't
+        // poison subsequent appends.
+        this.queue = result.catch(() => undefined);
+        return result;
+    }
+    /** Flush and close the file handle. Idempotent. */
+    async close() {
+        if (this.closed)
+            return;
+        // Final attestation BEFORE flipping `closed`, so we can still append.
+        if (this.attestor && this.attestOnClose && this.appendedCount > 0) {
+            await this.runAttestation();
+        }
+        this.closed = true;
+        // Drain the queue.
+        /* c8 ignore start */
+        try {
+            await this.queue;
+        }
+        catch {
+            // Defensive: queue is always re-wrapped with .catch(() => undefined)
+            // in append(), so this catch is structurally unreachable. Kept as
+            // belt-and-braces against future refactors.
+        }
+        /* c8 ignore stop */
+        if (this.handle) {
+            await this.handle.close();
+            this.handle = null;
+        }
+    }
+    /**
+     * Publish the current chain head to the configured attestor and emit
+     * `x_chain_attested` (success) or `x_chain_attestation_failed` (error).
+     * Idempotent on no-attestor or in-flight: callers can fire-and-forget.
+     *
+     * Exposed publicly so consumers can force a flush (e.g., on a
+     * manually-triggered checkpoint).
+     */
+    async runAttestation() {
+        if (!this.attestor || this.attestationInFlight || this.closed)
+            return;
+        this.attestationInFlight = true;
+        try {
+            // Build the payload from the most-recently-written record's hash. We
+            // synthesize a minimal AuditRecord wrapper for payloadFromRecord:
+            // only fields it reads are agent_id/session_id/signature, and we
+            // already have all three.
+            const head = this._tipHash;
+            // The last record's signature isn't trivially recoverable without
+            // re-reading the file; we publish with `signature: null` and let the
+            // verifier cross-check against the chain head only. The chain head is
+            // the load-bearing commitment; the signature is an auxiliary check
+            // that the verifier can run independently against the local log.
+            const synthRecord = {
+                agent_id: this.agentId,
+                session_id: this.sessionId,
+                signature: null,
+            };
+            const payload = payloadFromRecord(synthRecord, this.appendedCount, head);
+            try {
+                const receipt = await this.attestor.publish(payload);
+                await this.appendInternal({
+                    kind: 'x_chain_attested',
+                    status: 'approved',
+                    initiator: 'system',
+                    detail: {
+                        chain_head: head,
+                        records_in_session: this.appendedCount,
+                        receipt_id: receipt.receiptId,
+                        ...(receipt.url ? { receipt_url: receipt.url } : {}),
+                    },
+                });
+            }
+            catch (err) {
+                await this.appendInternal({
+                    kind: 'x_chain_attestation_failed',
+                    status: 'errored',
+                    initiator: 'system',
+                    detail: {
+                        chain_head: head,
+                        records_in_session: this.appendedCount,
+                        error: err instanceof Error ? err.message : String(err),
+                    },
+                });
+            }
+        }
+        finally {
+            this.attestationInFlight = false;
+        }
+    }
+    /**
+     * Internal-only append that bypasses the closed check (used by close() to
+     * write the final attestation row) and skips the attestation hook (to
+     * avoid recursion when writing attestation outcome rows).
+     */
+    async appendInternal(input) {
+        const result = this.queue.then(async () => {
+            await this.open();
+            return this.writeOne(input);
+        });
+        this.queue = result.catch(() => undefined);
+        return result;
+    }
+    // ---- internal --------------------------------------------------------------
+    async writeOne(input) {
+        /* c8 ignore start */
+        if (!this.handle) {
+            throw new Error('AuditLogWriter not open');
+        }
+        /* c8 ignore stop */
+        const record = {
+            v: SPEC_VERSION,
+            event_id: 'evt_' + ulid(),
+            ts: new Date().toISOString(),
+            agent_id: input.agentId ?? this.agentId,
+            session_id: input.sessionId ?? this.sessionId,
+            kind: input.kind,
+            status: input.status,
+            initiator: input.initiator,
+            prev_hash: this._tipHash,
+            ...(input.tool === undefined ? {} : { tool: input.tool }),
+            ...(input.model === undefined ? {} : { model: input.model }),
+            ...(input.detail === undefined ? {} : { detail: input.detail }),
+        };
+        // Sign or write `signature: null` per SPEC §2.6.
+        record.signature = null;
+        if (this.signWith) {
+            record.signature = signRecord(record, this.signWith);
+        }
+        const line = canonicalJsonStringify(record) + '\n';
+        await this.handle.write(line);
+        // Best-effort fsync. Errors here are not fatal; the OS will get to it.
+        try {
+            await this.handle.sync();
+        }
+        catch {
+            // Some platforms / filesystems disallow fsync; ignore.
+        }
+        this._tipHash = computeRecordHash(record);
+        this.appendedCount += 1;
+        // Fire attestation when we cross an attestEvery boundary. Skip if this
+        // append IS itself an attestation outcome row (set by runAttestation).
+        if (this.attestor &&
+            !this.attestationInFlight &&
+            this.appendedCount % this.attestEvery === 0) {
+            // Fire-and-forget: failures are recorded as audit rows by
+            // runAttestation itself. We don't await here so a slow attestor
+            // doesn't back up the writer queue. The internal queue still
+            // serializes the audit row writes.
+            void this.runAttestation();
+        }
+        return record;
+    }
+    /**
+     * Read the last non-empty record from the existing log. Returns null when
+     * the file is empty or contains only blank lines. Used during open() to
+     * seed the hash chain and expose the recovered record to onTipRecovered.
+     */
+    async recoverTipRecord() {
+        const buf = readFileSync(this.path, 'utf-8');
+        if (buf.length === 0)
+            return null;
+        const lines = buf.split('\n');
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i];
+            if (line === undefined || line.length === 0)
+                continue;
+            return JSON.parse(line);
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=writer.js.map

package/dist/audit/writer.js.map

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

package/dist/cli/guardian-baseline.d.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * guardian-baseline — offline behavioral-baseline CLI. SPEC §13 (v0.5.0+).
+ *
+ * Usage:
+ *   guardian-baseline <jsonl>                          # build profile(s), write to ~/.flowdot/audit/baselines/<agent>.json
+ *   guardian-baseline <jsonl> --agent <id>             # restrict to one agent_id
+ *   guardian-baseline <jsonl> --out <path>             # custom output path
+ *   guardian-baseline <jsonl> --check                  # compare jsonl against existing baseline(s); report deviations
+ *   guardian-baseline <jsonl> --check --sigma <N>      # custom σ threshold (default 3)
+ *
+ * Exit codes:
+ *   0 — success (profile written, or --check found zero deviations)
+ *   1 — IO error / bad JSONL / --check found deviations
+ *   2 — usage error (bad args)
+ *
+ * NOT A RUNTIME TRIPWIRE. Output is for operator review. The supervisor
+ * never consults baselines in the hot path.
+ */
+import { type DeviationReport } from '../audit/stats.js';
+export interface BaselineArgs {
+    path: string | undefined;
+    agent: string | undefined;
+    out: string | undefined;
+    check: boolean;
+    sigma: number;
+}
+/** Parse argv. Returns the parsed args or null on usage error. */
+export declare function parseArgs(argv: readonly string[]): BaselineArgs | null;
+/** Default baselines directory: `~/.flowdot/audit/baselines/`. */
+export declare function defaultBaselinesDir(): string;
+export interface BaselineRunResult {
+    exitCode: 0 | 1 | 2;
+    message: string;
+    profilesWritten: string[];
+    reports: DeviationReport[];
+}
+/** Programmatic entry point — useful for tests and library consumers. */
+export declare function runBaseline(args: BaselineArgs): Promise<BaselineRunResult>;
+/** Render a deviation report as human-readable text. */
+export declare function formatReport(report: DeviationReport): string;
+//# sourceMappingURL=guardian-baseline.d.ts.map

package/dist/cli/guardian-baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardian-baseline.d.ts","sourceRoot":"","sources":["../../src/cli/guardian-baseline.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;GAiBG;AAOH,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,GAAG,IAAI,CAoCtE;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AASD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAyBD,yEAAyE;AACzE,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2GhF;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAU5D"}

package/dist/cli/guardian-baseline.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+/**
+ * guardian-baseline — offline behavioral-baseline CLI. SPEC §13 (v0.5.0+).
+ *
+ * Usage:
+ *   guardian-baseline <jsonl>                          # build profile(s), write to ~/.flowdot/audit/baselines/<agent>.json
+ *   guardian-baseline <jsonl> --agent <id>             # restrict to one agent_id
+ *   guardian-baseline <jsonl> --out <path>             # custom output path
+ *   guardian-baseline <jsonl> --check                  # compare jsonl against existing baseline(s); report deviations
+ *   guardian-baseline <jsonl> --check --sigma <N>      # custom σ threshold (default 3)
+ *
+ * Exit codes:
+ *   0 — success (profile written, or --check found zero deviations)
+ *   1 — IO error / bad JSONL / --check found deviations
+ *   2 — usage error (bad args)
+ *
+ * NOT A RUNTIME TRIPWIRE. Output is for operator review. The supervisor
+ * never consults baselines in the hot path.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { AuditLogReader } from '../audit/reader.js';
+import { analyzeMultiAgent, compareToBaseline, } from '../audit/stats.js';
+/** Parse argv. Returns the parsed args or null on usage error. */
+export function parseArgs(argv) {
+    const args = argv.slice();
+    let path;
+    let agent;
+    let out;
+    let check = false;
+    let sigma = 3;
+    while (args.length > 0) {
+        const a = args.shift();
+        /* c8 ignore next */
+        if (a === undefined)
+            break;
+        if (a === '--agent') {
+            agent = args.shift();
+            if (agent === undefined)
+                return null;
+        }
+        else if (a === '--out') {
+            out = args.shift();
+            if (out === undefined)
+                return null;
+        }
+        else if (a === '--check') {
+            check = true;
+        }
+        else if (a === '--sigma') {
+            const v = args.shift();
+            if (v === undefined)
+                return null;
+            const n = Number(v);
+            if (!Number.isFinite(n) || n <= 0)
+                return null;
+            sigma = n;
+        }
+        else if (a.startsWith('--')) {
+            return null;
+        }
+        else if (path === undefined) {
+            path = a;
+        }
+        else {
+            return null;
+        }
+    }
+    if (path === undefined)
+        return null;
+    return { path, agent, out, check, sigma };
+}
+/** Default baselines directory: `~/.flowdot/audit/baselines/`. */
+export function defaultBaselinesDir() {
+    return process.env.FLOWDOT_BASELINES_DIR ?? join(homedir(), '.flowdot', 'audit', 'baselines');
+}
+function baselinePath(agentId, baselinesDir) {
+    // ASCII-safe filename derived from agent_id. agent_id is already
+    // expected to be short + ASCII per SPEC; we sanitize defensively.
+    const safe = agentId.replace(/[^a-zA-Z0-9._-]/g, '_');
+    return join(baselinesDir, `${safe}.json`);
+}
+/**
+ * Read an audit JSONL file and return one record per non-empty line.
+ * Caller is responsible for filtering by agent_id.
+ */
+async function loadRecords(path) {
+    const reader = await AuditLogReader.open(path);
+    try {
+        return await readAll(reader);
+    }
+    finally {
+        await reader.close();
+    }
+}
+async function readAll(reader) {
+    const out = [];
+    for await (const r of reader.records())
+        out.push(r);
+    return out;
+}
+/** Programmatic entry point — useful for tests and library consumers. */
+export async function runBaseline(args) {
+    if (!args.path) {
+        return { exitCode: 2, message: 'missing path', profilesWritten: [], reports: [] };
+    }
+    if (!existsSync(args.path)) {
+        return {
+            exitCode: 1,
+            message: `audit file not found: ${args.path}`,
+            profilesWritten: [],
+            reports: [],
+        };
+    }
+    let records;
+    try {
+        records = await loadRecords(args.path);
+    }
+    catch (err) {
+        return {
+            exitCode: 1,
+            /* c8 ignore next */
+            message: `failed to read audit file: ${err instanceof Error ? err.message : String(err)}`,
+            profilesWritten: [],
+            reports: [],
+        };
+    }
+    const profiles = analyzeMultiAgent(records);
+    const filteredProfiles = args.agent
+        ? new Map([...profiles].filter(([id]) => id === args.agent))
+        : profiles;
+    if (filteredProfiles.size === 0) {
+        return {
+            exitCode: 1,
+            message: args.agent
+                ? `no records for agent_id ${JSON.stringify(args.agent)}`
+                : 'no records found in audit file',
+            profilesWritten: [],
+            reports: [],
+        };
+    }
+    const baselinesDir = args.out ? dirname(args.out) : defaultBaselinesDir();
+    // --check path: compare each candidate profile against the existing baseline.
+    if (args.check) {
+        const reports = [];
+        for (const [agentId, profile] of filteredProfiles) {
+            const baseFile = args.out ?? baselinePath(agentId, baselinesDir);
+            if (!existsSync(baseFile)) {
+                return {
+                    exitCode: 1,
+                    message: `no baseline for ${agentId} at ${baseFile} — run without --check first to produce one`,
+                    profilesWritten: [],
+                    reports,
+                };
+            }
+            let baseline;
+            try {
+                baseline = JSON.parse(readFileSync(baseFile, 'utf-8'));
+            }
+            catch (err) {
+                return {
+                    exitCode: 1,
+                    /* c8 ignore next */
+                    message: `failed to read baseline ${baseFile}: ${err instanceof Error ? err.message : String(err)}`,
+                    profilesWritten: [],
+                    reports,
+                };
+            }
+            reports.push(compareToBaseline(profile, baseline, { sigmaThreshold: args.sigma }));
+        }
+        const totalDeviations = reports.reduce((s, r) => s + r.deviations.length, 0);
+        return {
+            exitCode: totalDeviations === 0 ? 0 : 1,
+            message: totalDeviations === 0
+                ? `OK: ${reports.length} agent(s) checked, no deviations at σ=${args.sigma}`
+                : `${totalDeviations} deviation(s) across ${reports.length} agent(s) at σ=${args.sigma}`,
+            profilesWritten: [],
+            reports,
+        };
+    }
+    // Write path: persist profiles to disk.
+    if (args.out && filteredProfiles.size > 1) {
+        return {
+            exitCode: 2,
+            message: '--out requires --agent when the file contains multiple agent_ids',
+            profilesWritten: [],
+            reports: [],
+        };
+    }
+    if (!existsSync(baselinesDir)) {
+        mkdirSync(baselinesDir, { recursive: true, mode: 0o700 });
+    }
+    const written = [];
+    for (const [agentId, profile] of filteredProfiles) {
+        const file = args.out ?? baselinePath(agentId, baselinesDir);
+        writeFileSync(file, JSON.stringify(profile, null, 2) + '\n', { mode: 0o600 });
+        written.push(file);
+    }
+    return {
+        exitCode: 0,
+        message: `wrote ${written.length} baseline(s)`,
+        profilesWritten: written,
+        reports: [],
+    };
+}
+/** Render a deviation report as human-readable text. */
+export function formatReport(report) {
+    if (report.deviations.length === 0) {
+        return `[${report.agent_id}] no deviations.`;
+    }
+    const lines = [`[${report.agent_id}] ${report.deviations.length} deviation(s):`];
+    for (const d of report.deviations) {
+        const sigmaStr = d.sigma === null ? 'σ=n/a' : `σ=${d.sigma.toFixed(2)}`;
+        lines.push(`  - ${d.metric}: observed=${d.observed}, baseline=${d.baseline}, ${sigmaStr} — ${d.note}`);
+    }
+    return lines.join('\n');
+}
+const USAGE = `Usage:
+  guardian-baseline <jsonl>                          # build profile(s)
+  guardian-baseline <jsonl> --agent <id>             # restrict to one agent_id
+  guardian-baseline <jsonl> --out <path>             # custom output path
+  guardian-baseline <jsonl> --check                  # compare against existing baseline(s)
+  guardian-baseline <jsonl> --check --sigma <N>      # custom σ threshold (default 3)
+
+Exit codes:
+  0 — success (profile written, or --check found zero deviations)
+  1 — IO error / bad JSONL / --check found deviations
+  2 — usage error
+`;
+/* c8 ignore start */
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (!parsed) {
+        process.stderr.write(USAGE);
+        process.exit(2);
+    }
+    const result = await runBaseline(parsed);
+    if (parsed.check) {
+        for (const r of result.reports) {
+            process.stdout.write(formatReport(r) + '\n');
+        }
+    }
+    else {
+        for (const p of result.profilesWritten) {
+            process.stdout.write(`wrote ${p}\n`);
+        }
+    }
+    if (result.exitCode !== 0) {
+        process.stderr.write(result.message + '\n');
+    }
+    process.exit(result.exitCode);
+}
+/* c8 ignore stop */
+// Run as CLI when invoked directly (not when imported as a module).
+const isMain = typeof process !== 'undefined' &&
+    typeof process.argv !== 'undefined' &&
+    process.argv[1] !== undefined &&
+    /guardian-baseline(\.js|\.ts)?$/.test(process.argv[1]);
+/* c8 ignore start */
+if (isMain) {
+    void main();
+}
+/* c8 ignore stop */
+//# sourceMappingURL=guardian-baseline.js.map

package/dist/cli/guardian-baseline.js.map

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

package/dist/cli/guardian-correlator.d.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * guardian-correlator — offline cross-surface correlation CLI. SPEC §14
+ * (v0.5.0+).
+ *
+ * Reads two or more audit JSONL files for the same `agent_id` and reports
+ * patterns that span surfaces: overlapping sessions, identical-args
+ * collisions, similar tool-frequency sequences. Writes findings as
+ * `x_cross_surface_match` JSONL to its own log (NEVER mutates source
+ * files).
+ *
+ * Usage:
+ *   guardian-correlator <file1.jsonl>:<surface1> <file2.jsonl>:<surface2> [...]
+ *   guardian-correlator <file1>:<surface1> <file2>:<surface2> --out <correlations.jsonl>
+ *   guardian-correlator <files...> --threshold <0..1>   # cosine threshold (default 0.9)
+ *   guardian-correlator <files...> --window-ms <N>      # args-hash window (default 60000)
+ *
+ * Exit codes:
+ *   0 — success (matches written or none found; either way, exit 0)
+ *   1 — IO error / bad JSONL
+ *   2 — usage error
+ *
+ * Not a runtime tripwire. Output is for operator review.
+ */
+import { type CorrelationMatch } from '../audit/correlation.js';
+export interface CorrelatorArgs {
+    /** Tuples of (path, surface-name). */
+    sources: {
+        path: string;
+        surface: string;
+    }[];
+    out: string | undefined;
+    threshold: number;
+    argsHashWindowMs: number;
+    similarityWindowMs: number;
+    similarityMinCalls: number;
+}
+export declare function parseArgs(argv: readonly string[]): CorrelatorArgs | null;
+export declare function defaultCorrelationsPath(): string;
+export interface CorrelatorRunResult {
+    exitCode: 0 | 1 | 2;
+    message: string;
+    matches: CorrelationMatch[];
+    outPath: string | undefined;
+}
+export declare function runCorrelator(args: CorrelatorArgs): Promise<CorrelatorRunResult>;
+//# sourceMappingURL=guardian-correlator.d.ts.map

package/dist/cli/guardian-correlator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardian-correlator.d.ts","sourceRoot":"","sources":["../../src/cli/guardian-correlator.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7C,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,GAAG,IAAI,CA4DxE;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAaD,wBAAsB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAyDtF"}