harnery 0.34.1 → 0.36.0

package/dist/core/storage/segments.js

@@ -0,0 +1,542 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, fdatasyncSync, constants as fsConstants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, rmSync, unlinkSync, writeSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
+import { gzipSync } from "node:zlib";
+import { parseLogRecord } from "./jsonl.js";
+import { mergeMetricsSidecar } from "./metrics.js";
+export class HarneryLogLeaseError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "HarneryLogLeaseError";
+    }
+}
+export function familyLogDirectory(family) {
+    const root = family.resolved_roots.find((candidate) => candidate.match === "provider-partition" && candidate.ownership !== "external");
+    if (!root?.partition)
+        throw new Error(`family ${family.id} has no writable log partition`);
+    return join(root.path, root.partition);
+}
+export class FileSegmentSink {
+    #options;
+    constructor(options) {
+        this.#options = {
+            ...options,
+            max_segment_bytes: options.max_segment_bytes ??
+                options.family.policy.rotation.max_segment_bytes.limit ??
+                10 * 1024 * 1024,
+            max_open_age_ms: options.max_open_age_ms ?? options.family.policy.rotation.max_open_age.limit ?? 86_400_000,
+            minimum_day_segment_bytes: options.minimum_day_segment_bytes ?? 256 * 1024,
+            lease_timeout_ms: options.lease_timeout_ms ?? options.family.lease_policy?.acquisition_timeout_ms ?? 2_000,
+            lease_retry_ms: options.lease_retry_ms ?? options.family.lease_policy?.retry_backoff_ms ?? 10,
+            lease_stale_ms: options.lease_stale_ms ?? options.family.lease_policy?.stale_owner_ms ?? 30_000,
+            write_sync: options.write_sync ?? nativeWriteSync,
+        };
+    }
+    async append(records, metrics = {}, durable = false, now = new Date()) {
+        if (records.length === 0)
+            return { appended_records: 0, appended_bytes: 0, rotated: false, synced: false };
+        return withFamilyLease(this.#options.directory, this.#options, async () => {
+            const directory = ensurePrivateDirectory(this.#options.directory);
+            const active = join(this.#options.directory, "active.jsonl");
+            let rotated = false;
+            if (existsSync(active) && shouldRotate(active, records, this.#options, now)) {
+                sealActive(active, this.#options, now);
+                rotated = true;
+            }
+            rejectExistingSymlink(active);
+            const fd = openSync(active, fsConstants.O_RDWR | fsConstants.O_APPEND | fsConstants.O_CREAT | noFollowFlag(), 0o600);
+            let bytes = 0;
+            try {
+                assertOpenFileIdentity(active, fd, directory);
+                assertCompleteTail(fd, active);
+                for (const record of records) {
+                    writeAllSync(fd, record, this.#options.write_sync);
+                    bytes += record.byteLength;
+                }
+                if (durable)
+                    fdatasyncSync(fd);
+                assertOpenFileIdentity(active, fd, directory);
+            }
+            finally {
+                closeSync(fd);
+            }
+            mergeMetricsSidecar(join(this.#options.directory, "metrics.json"), {
+                ...metrics,
+                appended: (metrics.appended ?? 0) + records.length,
+                bytes_appended: (metrics.bytes_appended ?? 0) + bytes,
+                rotations: (metrics.rotations ?? 0) + (rotated ? 1 : 0),
+                synced: (metrics.synced ?? 0) + (durable ? records.length : 0),
+            }, now);
+            return { appended_records: records.length, appended_bytes: bytes, rotated, synced: durable };
+        });
+    }
+}
+export function readSegmentManifest(directory, family) {
+    const path = join(directory, "manifest.json");
+    if (!existsSync(path)) {
+        if (!family)
+            throw new Error(`missing log manifest: ${path}`);
+        return emptyManifest(family);
+    }
+    const value = JSON.parse(readRegularFile(path, 4 * 1024 * 1024).toString("utf8"));
+    if (value.schema !== "harnery.log-manifest/v1" || !Array.isArray(value.segments)) {
+        throw new Error(`invalid log manifest: ${path}`);
+    }
+    if (family &&
+        (value.family_id !== family.id || value.policy_version !== family.policy.policy_version)) {
+        throw new Error(`log manifest identity mismatch: ${path}`);
+    }
+    const prunedThrough = value.pruned_through_sequence ?? 0;
+    if (!Number.isSafeInteger(prunedThrough) ||
+        prunedThrough < 0 ||
+        !Number.isSafeInteger(value.next_sequence) ||
+        value.next_sequence < 1 ||
+        prunedThrough >= value.next_sequence ||
+        value.segments.some((segment, index) => segment.sequence !== prunedThrough + index + 1 ||
+            !/^segments\/[0-9]{8}-[0-9]{8}\.jsonl\.gz$/.test(segment.file) ||
+            !Number.isSafeInteger(segment.bytes) ||
+            segment.bytes <= 0 ||
+            !Number.isFinite(Date.parse(segment.sealed_at)) ||
+            (index > 0 &&
+                Date.parse(segment.sealed_at) < Date.parse(value.segments[index - 1].sealed_at)) ||
+            !/^[a-f0-9]{64}$/.test(segment.sha256)) ||
+        value.next_sequence !== prunedThrough + value.segments.length + 1) {
+        throw new Error(`invalid log manifest sequence: ${path}`);
+    }
+    return value;
+}
+export function logManifestFingerprint(manifest) {
+    return createHash("sha256").update(JSON.stringify(manifest)).digest("hex");
+}
+/**
+ * Expire exactly the oldest retained segment. The manifest is authoritative,
+ * so it commits before unlink. Replays cover all four crash states without
+ * ever accepting an absent source from an old manifest.
+ */
+export async function pruneSealedLogSegment(options) {
+    if (!Number.isSafeInteger(options.sequence) || options.sequence < 1) {
+        throw new Error("invalid log retention sequence");
+    }
+    if (!/^segments\/[0-9]{8}-[0-9]{8}\.jsonl\.gz$/.test(options.file)) {
+        throw new Error("invalid log retention segment path");
+    }
+    if (!Number.isSafeInteger(options.expected_bytes) || options.expected_bytes <= 0) {
+        throw new Error("invalid log retention segment bytes");
+    }
+    if (!/^[a-f0-9]{64}$/.test(options.expected_file_sha256) ||
+        !/^[a-f0-9]{64}$/.test(options.expected_content_sha256) ||
+        !/^[a-f0-9]{64}$/.test(options.expected_manifest_fingerprint) ||
+        !/^[a-f0-9]{64}$/.test(options.result_manifest_fingerprint)) {
+        throw new Error("invalid log retention segment digest");
+    }
+    const policy = {
+        lease_timeout_ms: options.lease_timeout_ms ?? options.family.lease_policy?.acquisition_timeout_ms ?? 2_000,
+        lease_retry_ms: options.lease_retry_ms ?? options.family.lease_policy?.retry_backoff_ms ?? 10,
+        lease_stale_ms: options.lease_stale_ms ?? options.family.lease_policy?.stale_owner_ms ?? 30_000,
+    };
+    return withFamilyLease(options.directory, policy, () => {
+        const manifest = readSegmentManifest(options.directory, options.family);
+        const currentManifestFingerprint = logManifestFingerprint(manifest);
+        const prunedThrough = manifest.pruned_through_sequence ?? 0;
+        const target = containedSegmentPath(options.directory, options.file);
+        if (options.sequence <= prunedThrough) {
+            if (currentManifestFingerprint !== options.result_manifest_fingerprint) {
+                throw new Error("log retention manifest changed after the planned prune");
+            }
+            if (!pathExists(target))
+                return "already_applied";
+            assertExactSegment(target, options.expected_bytes, options.expected_file_sha256);
+            unlinkSync(target);
+            return "applied";
+        }
+        if (options.sequence !== prunedThrough + 1) {
+            throw new Error("log retention segment is not the oldest retained sequence");
+        }
+        if (currentManifestFingerprint !== options.expected_manifest_fingerprint) {
+            throw new Error("log retention manifest changed after planning");
+        }
+        const entry = manifest.segments[0];
+        if (!entry ||
+            entry.sequence !== options.sequence ||
+            entry.file !== options.file ||
+            entry.sha256 !== options.expected_content_sha256) {
+            throw new Error("log retention segment does not match the current manifest");
+        }
+        if (!pathExists(target)) {
+            throw new Error("log retention source is absent while the manifest still references it");
+        }
+        assertExactSegment(target, options.expected_bytes, options.expected_file_sha256);
+        const next = {
+            ...manifest,
+            pruned_through_sequence: options.sequence,
+            segments: manifest.segments.slice(1),
+        };
+        if (logManifestFingerprint(next) !== options.result_manifest_fingerprint) {
+            throw new Error("log retention predicted manifest does not match apply state");
+        }
+        atomicJson(join(options.directory, "manifest.json"), next);
+        options.after_manifest_commit?.();
+        assertExactSegment(target, options.expected_bytes, options.expected_file_sha256);
+        unlinkSync(target);
+        return "applied";
+    });
+}
+export async function withFamilyLease(directory, policy, operation) {
+    ensurePrivateDirectory(directory);
+    const lease = join(directory, ".append-lease");
+    const started = Date.now();
+    let owner;
+    while (true) {
+        try {
+            mkdirSync(lease, { mode: 0o700 });
+            const leaseIdentity = captureDirectoryIdentity(lease);
+            owner = {
+                owner_id: randomUUID(),
+                pid: process.pid,
+                acquired_at: new Date().toISOString(),
+            };
+            writeNewFile(join(lease, "owner.json"), Buffer.from(`${JSON.stringify(owner)}\n`));
+            assertDirectoryIdentity(leaseIdentity);
+            break;
+        }
+        catch (error) {
+            if (pathExists(lease) && !safeLeaseDirectory(lease)) {
+                throw new HarneryLogLeaseError("wrong_type", `log lease is not a directory: ${lease}`);
+            }
+            if (recoverStaleLease(lease, policy.lease_stale_ms))
+                continue;
+            if (Date.now() - started >= policy.lease_timeout_ms) {
+                throw new HarneryLogLeaseError("timeout", `timed out acquiring log lease: ${lease}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, policy.lease_retry_ms));
+            void error;
+        }
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        if (owner)
+            releaseOwnedLease(lease, owner);
+    }
+}
+function shouldRotate(active, incoming, options, now) {
+    const stat = regularFileStat(active);
+    const incomingBytes = incoming.reduce((sum, record) => sum + record.byteLength, 0);
+    if (stat.size + incomingBytes > options.max_segment_bytes)
+        return stat.size > 0;
+    const age = now.getTime() - stat.mtimeMs;
+    if (age >= options.max_open_age_ms)
+        return stat.size > 0;
+    const opened = new Date(stat.mtimeMs);
+    return (opened.toDateString() !== now.toDateString() && stat.size >= options.minimum_day_segment_bytes);
+}
+function sealActive(active, options, now) {
+    const family = options.family;
+    const directory = dirname(active);
+    const manifest = readSegmentManifest(directory, family);
+    const maximumActiveBytes = Math.max(options.max_segment_bytes, family.policy.records.max_record_bytes.limit ?? 1024 * 1024);
+    const content = readRegularFile(active, maximumActiveBytes);
+    if (content.byteLength === 0)
+        return;
+    const lines = validateCompleteLogJsonl(content, active, family);
+    const sequence = manifest.next_sequence;
+    const name = `${now.toISOString().slice(0, 10).replaceAll("-", "")}-${String(sequence).padStart(8, "0")}.jsonl.gz`;
+    const target = join(directory, "segments", name);
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.tmp-${process.pid}-${randomUUID()}`;
+    const compressed = gzipSync(content);
+    writeNewFile(temporary, compressed);
+    rejectExistingSymlink(target);
+    renameSync(temporary, target);
+    assertRegularPath(target, captureDirectoryIdentity(dirname(target)));
+    const timestamps = lines
+        .map((record) => record.emitted_at)
+        .filter((value) => Boolean(value));
+    const next = {
+        ...manifest,
+        next_sequence: sequence + 1,
+        segments: [
+            ...manifest.segments,
+            {
+                sequence,
+                file: join("segments", basename(target)).replaceAll("\\", "/"),
+                bytes: content.byteLength,
+                records: lines.length,
+                ...(timestamps[0] ? { first_emitted_at: timestamps[0] } : {}),
+                ...(timestamps.at(-1) ? { last_emitted_at: timestamps.at(-1) } : {}),
+                sealed_at: now.toISOString(),
+                sha256: createHash("sha256").update(content).digest("hex"),
+            },
+        ],
+    };
+    const sealedManifest = join(directory, "manifests", `${String(sequence).padStart(8, "0")}.json`);
+    mkdirSync(dirname(sealedManifest), { recursive: true, mode: 0o700 });
+    writeNewFile(sealedManifest, Buffer.from(`${JSON.stringify(next)}\n`));
+    atomicJson(join(directory, "manifest.json"), next);
+    truncateRegularFile(active);
+}
+function emptyManifest(family) {
+    return {
+        schema: "harnery.log-manifest/v1",
+        family_id: family.id,
+        policy_version: family.policy.policy_version,
+        next_sequence: 1,
+        segments: [],
+    };
+}
+function containedSegmentPath(directory, relativePath) {
+    const path = join(directory, ...relativePath.split("/"));
+    const parent = captureDirectoryIdentity(dirname(path));
+    const fromRoot = relative(realpathSync(directory), parent.real_path);
+    if (fromRoot.startsWith("..") || isAbsolute(fromRoot)) {
+        throw new Error("log retention segment escapes its family directory");
+    }
+    return path;
+}
+function assertExactSegment(path, expectedBytes, expectedSha256) {
+    const stat = regularFileStat(path);
+    if (stat.nlink !== 1)
+        throw new Error(`log retention rejects hard-linked segment: ${path}`);
+    if (stat.size !== expectedBytes)
+        throw new Error(`log retention segment size changed: ${path}`);
+    const bytes = readRegularFile(path, expectedBytes);
+    if (createHash("sha256").update(bytes).digest("hex") !== expectedSha256) {
+        throw new Error(`log retention segment digest changed: ${path}`);
+    }
+}
+function atomicJson(path, value) {
+    const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    writeNewFile(temporary, Buffer.from(`${JSON.stringify(value)}\n`));
+    rejectExistingSymlink(path);
+    renameSync(temporary, path);
+    assertRegularPath(path, captureDirectoryIdentity(dirname(path)));
+}
+function recoverStaleLease(lease, maximumAgeMs) {
+    let identity;
+    let raw;
+    try {
+        identity = captureDirectoryIdentity(lease);
+        raw = readRegularFile(join(lease, "owner.json"), 4_096).toString("utf8");
+    }
+    catch {
+        return false;
+    }
+    let owner;
+    try {
+        owner = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (typeof owner.owner_id !== "string" ||
+        owner.owner_id.length === 0 ||
+        !Number.isSafeInteger(owner.pid) ||
+        !Number.isFinite(Date.parse(owner.acquired_at)) ||
+        Date.now() - Date.parse(owner.acquired_at) < maximumAgeMs ||
+        processIsAlive(owner.pid)) {
+        return false;
+    }
+    try {
+        assertDirectoryIdentity(identity);
+        if (readRegularFile(join(lease, "owner.json"), 4_096).toString("utf8") !== raw)
+            return false;
+        rmSync(lease, { recursive: true, force: false });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function releaseOwnedLease(lease, owner) {
+    try {
+        const current = JSON.parse(readRegularFile(join(lease, "owner.json"), 4_096).toString("utf8"));
+        if (current.owner_id !== owner.owner_id)
+            return;
+        rmSync(lease, { recursive: true, force: false });
+    }
+    catch {
+        // A missing or replaced lease does not belong to this operation.
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+function ensurePrivateDirectory(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    return captureDirectoryIdentity(path);
+}
+function captureDirectoryIdentity(path) {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink())
+        throw new Error(`log storage rejects symlink: ${path}`);
+    if (!stat.isDirectory())
+        throw new Error(`log storage path is not a directory: ${path}`);
+    return { path, real_path: realpathSync(path), dev: stat.dev, ino: stat.ino };
+}
+function assertDirectoryIdentity(identity) {
+    const current = lstatSync(identity.path);
+    if (current.isSymbolicLink() ||
+        !current.isDirectory() ||
+        current.dev !== identity.dev ||
+        current.ino !== identity.ino ||
+        realpathSync(identity.path) !== identity.real_path) {
+        throw new Error(`log storage directory identity changed: ${identity.path}`);
+    }
+}
+function rejectExistingSymlink(path) {
+    try {
+        if (lstatSync(path).isSymbolicLink())
+            throw new Error(`log storage rejects symlink: ${path}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function assertOpenFileIdentity(path, fd, parent) {
+    assertDirectoryIdentity(parent);
+    const opened = fstatSync(fd);
+    const current = lstatSync(path);
+    if (!opened.isFile() ||
+        current.isSymbolicLink() ||
+        !current.isFile() ||
+        opened.dev !== current.dev ||
+        opened.ino !== current.ino) {
+        throw new Error(`log storage path identity changed: ${path}`);
+    }
+    const fromParent = relative(parent.real_path, realpathSync(path));
+    if (fromParent.startsWith("..") || isAbsolute(fromParent)) {
+        throw new Error(`log storage path escapes parent boundary: ${path}`);
+    }
+}
+function assertRegularPath(path, parent) {
+    const fd = openSync(path, fsConstants.O_RDONLY | noFollowFlag());
+    try {
+        assertOpenFileIdentity(path, fd, parent);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function regularFileStat(path) {
+    const parent = captureDirectoryIdentity(dirname(path));
+    rejectExistingSymlink(path);
+    const fd = openSync(path, fsConstants.O_RDONLY | noFollowFlag());
+    try {
+        assertOpenFileIdentity(path, fd, parent);
+        return fstatSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readRegularFile(path, maximumBytes) {
+    const parent = captureDirectoryIdentity(dirname(path));
+    rejectExistingSymlink(path);
+    const fd = openSync(path, fsConstants.O_RDONLY | noFollowFlag());
+    try {
+        assertOpenFileIdentity(path, fd, parent);
+        const stat = fstatSync(fd);
+        if (stat.size > maximumBytes)
+            throw new Error(`log storage file exceeds bound: ${path}`);
+        const content = readFileSync(fd);
+        assertOpenFileIdentity(path, fd, parent);
+        return content;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function writeNewFile(path, content) {
+    const parent = captureDirectoryIdentity(dirname(path));
+    const fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | noFollowFlag(), 0o600);
+    try {
+        assertOpenFileIdentity(path, fd, parent);
+        writeAllSync(fd, content, nativeWriteSync);
+        fsyncSync(fd);
+        assertOpenFileIdentity(path, fd, parent);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function truncateRegularFile(path) {
+    const parent = captureDirectoryIdentity(dirname(path));
+    rejectExistingSymlink(path);
+    const fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_TRUNC | noFollowFlag());
+    try {
+        fdatasyncSync(fd);
+        assertOpenFileIdentity(path, fd, parent);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function assertCompleteTail(fd, path) {
+    const stat = fstatSync(fd);
+    if (stat.size === 0)
+        return;
+    const last = Buffer.allocUnsafe(1);
+    if (readSync(fd, last, 0, 1, stat.size - 1) !== 1 || last[0] !== 10) {
+        throw new Error(`log storage has a partial JSONL record: ${path}`);
+    }
+}
+function validateCompleteLogJsonl(content, path, family) {
+    if (content.at(-1) !== 10)
+        throw new Error(`log storage has a partial JSONL record: ${path}`);
+    const rawLines = content.toString("utf8").split("\n");
+    rawLines.pop();
+    return rawLines.map((line) => {
+        if (!line)
+            throw new Error(`log storage has a malformed JSONL record: ${path}`);
+        const record = parseLogRecord(line);
+        if (record.family_id !== family.id || record.policy_version !== family.policy.policy_version) {
+            throw new Error(`log storage record identity mismatch: ${path}`);
+        }
+        return record;
+    });
+}
+function writeAllSync(fd, buffer, writer) {
+    let offset = 0;
+    while (offset < buffer.byteLength) {
+        const written = writer(fd, buffer, offset, buffer.byteLength - offset);
+        if (!Number.isSafeInteger(written) || written <= 0 || written > buffer.byteLength - offset) {
+            throw new Error("log storage write made no forward progress");
+        }
+        offset += written;
+    }
+}
+function nativeWriteSync(fd, buffer, offset, length) {
+    return writeSync(fd, buffer, offset, length);
+}
+function safeLeaseDirectory(path) {
+    try {
+        return !lstatSync(path).isSymbolicLink() && lstatSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function pathExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function noFollowFlag() {
+    return fsConstants.O_NOFOLLOW ?? 0;
+}

package/dist/core/storage/sink-graph.d.ts

@@ -0,0 +1,65 @@
+export type HarnerySinkEdgeKind = "primary" | "diagnostic" | "fallback";
+export type HarnerySinkRecordOrigin = "structured-log" | "raw-process" | "cli-emission";
+export type HarneryCapturedStream = "stdout" | "stderr";
+export interface HarnerySinkRecord<T = unknown> {
+    origin: HarnerySinkRecordOrigin;
+    payload: T;
+}
+export interface HarnerySinkDelivery<T = unknown> extends HarnerySinkRecord<T> {
+    entry_sink_id: string;
+    sink_id: string;
+    route: "entry" | HarnerySinkEdgeKind;
+    source_sink_id?: string;
+}
+export interface HarnerySink {
+    id: string;
+    deliver(delivery: HarnerySinkDelivery): void | Promise<void>;
+    emits_stream?: HarneryCapturedStream;
+    captures?: {
+        origin: HarneryCapturedStream | "cli-emission";
+        origin_sink_id?: string;
+    };
+}
+export interface HarnerySinkEdge {
+    from: string;
+    to: string;
+    kind: HarnerySinkEdgeKind;
+}
+export type HarnerySinkGraphErrorCode = "duplicate_sink" | "invalid_sink" | "unknown_sink" | "duplicate_edge" | "self_edge" | "cycle" | "cli_emission_capture" | "capture_origin_invalid" | "capture_loop" | "fanout_limit" | "graph_limit";
+export declare class HarnerySinkGraphError extends Error {
+    readonly code: HarnerySinkGraphErrorCode;
+    constructor(code: HarnerySinkGraphErrorCode, message: string);
+}
+export type HarnerySinkDeliveryFailureCode = "sink_delivery_failed" | "delivery_budget_exhausted";
+export declare class HarnerySinkDeliveryError extends Error {
+    readonly code: HarnerySinkDeliveryFailureCode;
+    readonly sink_id: string;
+    readonly cause?: unknown | undefined;
+    constructor(code: HarnerySinkDeliveryFailureCode, sink_id: string, message: string, cause?: unknown | undefined);
+}
+export interface HarnerySinkDeliveryFailure {
+    code: HarnerySinkDeliveryFailureCode;
+    sink_id: string;
+    route: HarnerySinkDelivery["route"];
+    error: HarnerySinkDeliveryError;
+}
+export interface HarnerySinkDeliveryResult {
+    attempted: number;
+    delivered: readonly string[];
+    failures: readonly HarnerySinkDeliveryFailure[];
+    truncated: boolean;
+}
+export interface HarnerySinkGraphOptions {
+    max_sinks?: number;
+    max_edges?: number;
+    max_fanout?: number;
+    max_deliveries?: number;
+}
+export declare class HarnerySinkGraph {
+    #private;
+    readonly sinks: readonly Readonly<HarnerySink>[];
+    readonly edges: readonly Readonly<HarnerySinkEdge>[];
+    constructor(sinks: readonly HarnerySink[], edges: readonly HarnerySinkEdge[], options?: HarnerySinkGraphOptions);
+    deliver(entrySinkId: string, record: HarnerySinkRecord): Promise<HarnerySinkDeliveryResult>;
+}
+//# sourceMappingURL=sink-graph.d.ts.map

package/dist/core/storage/sink-graph.d.ts.map

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