@llblab/pi-kit 0.18.2 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -44,7 +44,7 @@
     "@llblab/pi-clean-room": "0.1.1",
     "@llblab/pi-codex-usage": "0.10.0",
     "@llblab/pi-grow-loop": "0.8.1",
-    "@llblab/pi-state-flow": "0.16.3",
+    "@llblab/pi-state-flow": "0.17.2",
     "@llblab/pi-telegram": "0.50.1",
     "@llblab/skills": "1.15.0"
   },

package/node_modules/@llblab/pi-state-flow/dist/lib/discovery.d.ts

@@ -1,21 +0,0 @@
-import { type ArtifactSourceIdentity } from "./artifact.ts";
-/** Opaque source metadata discovered without decoding or retaining Markdown bodies. */
-export interface ArtifactSourceCandidate extends ArtifactSourceIdentity {
-    /** Raw byte count used as a conservative maintenance token-budget ceiling. */
-    bytes: number;
-}
-export interface GlobalMarkdownDiscoveryResult {
-    sources: ArtifactSourceCandidate[];
-    removed: string[];
-    unavailable?: string;
-}
-export declare function getKnowledgeRoot(agentDir?: string): string;
-/** Discover regular `*.md` files beneath a Knowledge root without following directory or file symlinks. */
-export declare function discoverGlobalMarkdownSources(knowledgeRoot?: string): ArtifactSourceCandidate[];
-/** Source-owner discovery; retained paths let restart/status re-observe removals until publication. */
-export declare class GlobalMarkdownDiscovery {
-    #private;
-    readonly knowledgeRoot: string;
-    constructor(knowledgeRoot?: string);
-    refresh(retainedPaths?: Iterable<string>): GlobalMarkdownDiscoveryResult;
-}

package/node_modules/@llblab/pi-state-flow/dist/lib/discovery.js

@@ -1,125 +0,0 @@
-import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { hashArtifactSource } from "./artifact.js";
-export function getKnowledgeRoot(agentDir = getAgentDir()) {
-    return resolve(agentDir, "knowledge");
-}
-function errorCode(error) {
-    return error instanceof Error && "code" in error
-        ? error.code
-        : undefined;
-}
-function isMissing(error) {
-    return errorCode(error) === "ENOENT";
-}
-function isInside(root, path) {
-    const child = relative(root, path);
-    return child === "" || (!isAbsolute(child) && child !== ".." && !child.startsWith(`..${sep}`));
-}
-function canonicalExistingPath(path) {
-    try {
-        return realpathSync.native(path);
-    }
-    catch (error) {
-        if (isMissing(error))
-            return undefined;
-        throw error;
-    }
-}
-function readRegularFile(path) {
-    let descriptor;
-    try {
-        descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
-        if (!fstatSync(descriptor).isFile())
-            return undefined;
-        return readFileSync(descriptor);
-    }
-    catch (error) {
-        if (isMissing(error) || errorCode(error) === "ELOOP")
-            return undefined;
-        throw error;
-    }
-    finally {
-        if (descriptor !== undefined)
-            closeSync(descriptor);
-    }
-}
-/** Discover regular `*.md` files beneath a Knowledge root without following directory or file symlinks. */
-export function discoverGlobalMarkdownSources(knowledgeRoot = getKnowledgeRoot()) {
-    const configuredRoot = resolve(knowledgeRoot);
-    const root = canonicalExistingPath(configuredRoot);
-    if (root === undefined)
-        return [];
-    if (!statSync(root).isDirectory())
-        throw new Error(`Knowledge root is not a directory: ${configuredRoot}`);
-    const sources = [];
-    const visit = (directory) => {
-        const entries = readdirSync(directory, { withFileTypes: true })
-            .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
-        for (const entry of entries) {
-            const candidate = join(directory, entry.name);
-            let metadata;
-            try {
-                metadata = lstatSync(candidate);
-            }
-            catch (error) {
-                if (isMissing(error))
-                    continue;
-                throw error;
-            }
-            if (metadata.isSymbolicLink())
-                continue;
-            const canonical = canonicalExistingPath(candidate);
-            if (canonical === undefined || !isInside(root, canonical))
-                continue;
-            if (metadata.isDirectory()) {
-                visit(canonical);
-                continue;
-            }
-            if (!metadata.isFile() || !entry.name.endsWith(".md"))
-                continue;
-            const body = readRegularFile(canonical);
-            if (body === undefined)
-                continue;
-            sources.push({ path: canonical, hash: hashArtifactSource(body), bytes: body.byteLength });
-        }
-    };
-    visit(root);
-    return sources.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
-}
-/** Prove absence inside the current source root without following excluded symlink components. */
-function missingOwnedMarkdown(root, path) {
-    if (!isAbsolute(path) || path !== resolve(path) || path === root || !isInside(root, path) || !path.endsWith(".md"))
-        return false;
-    let candidate = root;
-    for (const segment of relative(root, path).split(sep)) {
-        candidate = join(candidate, segment);
-        const metadata = lstatSync(candidate, { throwIfNoEntry: false });
-        if (metadata === undefined)
-            return true;
-        if (metadata.isSymbolicLink() || !metadata.isDirectory())
-            return false;
-    }
-    return false;
-}
-/** Source-owner discovery; retained paths let restart/status re-observe removals until publication. */
-export class GlobalMarkdownDiscovery {
-    knowledgeRoot;
-    #knownPaths = new Set();
-    constructor(knowledgeRoot = getKnowledgeRoot()) {
-        this.knowledgeRoot = resolve(knowledgeRoot);
-    }
-    refresh(retainedPaths = this.#knownPaths) {
-        const root = canonicalExistingPath(this.knowledgeRoot);
-        if (root === undefined)
-            return { sources: [], removed: [], unavailable: `Knowledge root is unavailable: ${this.knowledgeRoot}` };
-        const sources = discoverGlobalMarkdownSources(root);
-        const currentPaths = new Set(sources.map((source) => source.path));
-        const removed = [...new Set(retainedPaths)]
-            .filter((path) => !currentPaths.has(path) && missingOwnedMarkdown(root, path))
-            .sort();
-        this.#knownPaths = currentPaths;
-        return { sources, removed };
-    }
-}

package/node_modules/@llblab/pi-state-flow/dist/lib/maintenance.d.ts

@@ -1,36 +0,0 @@
-import { type ArtifactProvenance, type ArtifactSourceIdentity } from "./artifact.ts";
-import type { ArtifactSourceCandidate } from "./discovery.ts";
-export declare const DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS = 1;
-export declare const DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES: number;
-export declare const DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS: number;
-export interface ArtifactMaintenanceOptions {
-    /** Stable cycle time supplied by the caller. */
-    now?: Date | number | string;
-    /** A source must be at least this old. Missing/unparseable timestamps rank as oldest. */
-    minimumAgeMs?: number;
-    /** Strict source-read count ceiling for this cycle. */
-    maxReads?: number;
-    /** Strict source-byte ceiling; bytes conservatively upper-bound source tokenizer input. */
-    maxSourceBytes?: number;
-}
-export interface ArtifactMaintenanceRequest extends ArtifactSourceIdentity {
-    reason: "maintenance";
-    sourceBytes: number;
-}
-export interface ArtifactMaintenancePlan {
-    requiresCompilation: ArtifactMaintenanceRequest[];
-    deferred: ArtifactMaintenanceRequest[];
-    budget: {
-        maxReads: number;
-        maxSourceBytes: number;
-        usedReads: number;
-        usedSourceBytes: number;
-    };
-}
-/**
- * Select a bounded, oldest-first maintenance cohort from otherwise fresh artifacts.
- *
- * This planner is opt-in and side-effect free. Correctness invalidations remain the
- * responsibility of planArtifactInvalidation; they are never displaced by maintenance.
- */
-export declare function planArtifactMaintenance(sources: readonly ArtifactSourceCandidate[], registry: Readonly<Record<string, unknown>>, compiler: string, options?: ArtifactMaintenanceOptions, provenance?: Readonly<Record<string, ArtifactProvenance>>): ArtifactMaintenancePlan;

package/node_modules/@llblab/pi-state-flow/dist/lib/maintenance.js

@@ -1,98 +0,0 @@
-import { classifyArtifactFreshness, } from "./artifact.js";
-import { isObject } from "./json.js";
-export const DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS = 1;
-export const DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES = 16 * 1024;
-export const DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
-function nonNegativeSafeInteger(value, name) {
-    if (!Number.isSafeInteger(value) || value < 0)
-        throw new Error(`${name} must be a non-negative safe integer`);
-    return value;
-}
-function cycleTime(value) {
-    const timestamp = value === undefined
-        ? Date.now()
-        : value instanceof Date
-            ? value.getTime()
-            : typeof value === "number"
-                ? value
-                : Date.parse(value);
-    if (!Number.isFinite(timestamp))
-        throw new Error("Artifact maintenance cycle time must be valid");
-    return timestamp;
-}
-function compiledTime(entry, legacy) {
-    const timestamp = entry?.malformed === true ? undefined
-        : entry !== undefined && Object.hasOwn(entry, "compiledAt") ? entry.compiledAt
-            : legacy;
-    if (typeof timestamp !== "string")
-        return Number.NEGATIVE_INFINITY;
-    const parsed = Date.parse(timestamp);
-    return Number.isFinite(parsed) ? parsed : Number.NEGATIVE_INFINITY;
-}
-function request(source) {
-    return {
-        path: source.path,
-        hash: source.hash,
-        reason: "maintenance",
-        sourceBytes: source.bytes,
-    };
-}
-/**
- * Select a bounded, oldest-first maintenance cohort from otherwise fresh artifacts.
- *
- * This planner is opt-in and side-effect free. Correctness invalidations remain the
- * responsibility of planArtifactInvalidation; they are never displaced by maintenance.
- */
-export function planArtifactMaintenance(sources, registry, compiler, options = {}, provenance = {}) {
-    if (!isObject(registry))
-        throw new Error("Artifacts must be a path-keyed JSON object");
-    const now = cycleTime(options.now);
-    const minimumAgeMs = nonNegativeSafeInteger(options.minimumAgeMs ?? DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS, "Artifact maintenance minimum age");
-    const maxReads = nonNegativeSafeInteger(options.maxReads ?? DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS, "Artifact maintenance read budget");
-    const maxSourceBytes = nonNegativeSafeInteger(options.maxSourceBytes ?? DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES, "Artifact maintenance source-byte budget");
-    const seen = new Set();
-    const eligible = [];
-    for (const source of sources) {
-        if (seen.has(source.path))
-            throw new Error(`Duplicate artifact source path: ${source.path}`);
-        seen.add(source.path);
-        nonNegativeSafeInteger(source.bytes, `Artifact source bytes at ${source.path}`);
-        const metadata = Object.hasOwn(registry, source.path) ? registry[source.path] : undefined;
-        const entry = Object.hasOwn(provenance, source.path) ? provenance[source.path] : undefined;
-        const freshness = classifyArtifactFreshness(source, metadata, compiler, false, entry);
-        if (freshness.kind !== "fresh")
-            continue;
-        const compiledAt = compiledTime(entry, isObject(metadata) ? metadata.compiled_at : undefined);
-        if (compiledAt !== Number.NEGATIVE_INFINITY && now - compiledAt < minimumAgeMs)
-            continue;
-        eligible.push({ source, compiledAt });
-    }
-    eligible.sort((left, right) => {
-        if (left.compiledAt !== right.compiledAt)
-            return left.compiledAt - right.compiledAt;
-        return left.source.path < right.source.path ? -1 : left.source.path > right.source.path ? 1 : 0;
-    });
-    const requiresCompilation = [];
-    const deferred = [];
-    let usedSourceBytes = 0;
-    for (const candidate of eligible) {
-        const next = request(candidate.source);
-        if (requiresCompilation.length >= maxReads
-            || candidate.source.bytes > maxSourceBytes - usedSourceBytes) {
-            deferred.push(next);
-            continue;
-        }
-        requiresCompilation.push(next);
-        usedSourceBytes += candidate.source.bytes;
-    }
-    return {
-        requiresCompilation,
-        deferred,
-        budget: {
-            maxReads,
-            maxSourceBytes,
-            usedReads: requiresCompilation.length,
-            usedSourceBytes,
-        },
-    };
-}

package/node_modules/@llblab/pi-state-flow/dist/lib/migration.d.ts

@@ -1,13 +0,0 @@
-import { type DurableFileBase, type OwnedFileUpdate } from "./durable.ts";
-import { type StateScope } from "./state.ts";
-export interface LegacyStorageMigration {
-    bases: DurableFileBase[];
-    updates: OwnedFileUpdate[];
-    scopes: StateScope[];
-}
-/** Read-only activation eligibility, before global migration or any repository publication. */
-export declare function hasCwdMaterialization(cwd: string, repositoryRoot: string): boolean;
-/** Detect predecessor snapshots, temporal envelopes, or pre-intents semantic states without mutating the store. */
-export declare function hasLegacyStateSources(cwd: string, sessionId: string, repositoryRoot: string, sessionKey?: string): boolean;
-/** Plan from current scope snapshots only; old explanatory journals are never replay input. */
-export declare function planLegacyStorageMigration(cwd: string, sessionId: string, repositoryRoot: string, _origin?: string, sessionKey?: string): LegacyStorageMigration;

package/node_modules/@llblab/pi-state-flow/dist/lib/migration.js

@@ -1,167 +0,0 @@
-// Domain: predecessor temporal-envelope migration planning; Git/files backends own publication and rollback.
-import { lstatSync, readFileSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { captureOwnedFileBases, cwdScopePaths, parseScopeStream, serializeScopeMetadata, serializeScopeStream, sessionScopeKey, sessionScopePaths, } from "./durable.js";
-import { parseSessionRuntime, serializeSessionRuntime } from "./snapshot.js";
-import { migratePreIntentState } from "./state.js";
-/** Discover every owner-proven CWD and session cohort beneath the configured store. */
-function migrationDirectories(cwd, sessionId, root, sessionKey) {
-    const selectedCwd = cwdScopePaths(cwd, root).directory;
-    const selectedSession = sessionScopePaths(cwd, sessionId, root, sessionKey).directory;
-    const directories = [{ directory: root, scope: "global" }];
-    const cwdOwners = new Map([[selectedCwd, resolve(cwd)]]);
-    if (lstatSync(root, { throwIfNoEntry: false }) !== undefined) {
-        for (const entry of readdirSync(root, { withFileTypes: true })) {
-            if (!entry.isDirectory())
-                continue;
-            const directory = join(root, entry.name);
-            let checkpoint;
-            let meta;
-            try {
-                checkpoint = JSON.parse(readFileSync(join(directory, "checkpoint.json"), "utf8"));
-            }
-            catch {
-                continue;
-            }
-            try {
-                meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
-            }
-            catch { /* predecessor metadata may be absent */ }
-            const owner = checkpoint && typeof checkpoint === "object" && !Array.isArray(checkpoint) && checkpoint.owner
-                ? checkpoint.owner
-                : meta && typeof meta === "object" && !Array.isArray(meta) ? meta.owner : undefined;
-            if (owner && typeof owner.cwd === "string" && resolve(owner.cwd) === owner.cwd)
-                cwdOwners.set(directory, owner.cwd);
-        }
-    }
-    for (const [cwdDirectory, cwdOwner] of cwdOwners) {
-        directories.push({ directory: cwdDirectory, scope: "cwd", cwdIdentity: cwdOwner });
-        if (lstatSync(cwdDirectory, { throwIfNoEntry: false }) === undefined)
-            continue;
-        for (const entry of readdirSync(cwdDirectory, { withFileTypes: true })) {
-            if (!entry.isDirectory())
-                continue;
-            try {
-                sessionScopeKey(entry.name);
-            }
-            catch {
-                continue;
-            }
-            const directory = join(cwdDirectory, entry.name);
-            let meta;
-            let runtime;
-            try {
-                meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
-            }
-            catch {
-                continue;
-            }
-            try {
-                runtime = JSON.parse(readFileSync(join(directory, "runtime.json"), "utf8"));
-            }
-            catch { /* predecessor sessions keep identity in meta.json */ }
-            const identity = meta && typeof meta === "object" && !Array.isArray(meta) && meta.identity !== undefined
-                ? meta.identity
-                : runtime && typeof runtime === "object" && !Array.isArray(runtime) ? runtime.identity : undefined;
-            if (!identity || typeof identity !== "object" || Array.isArray(identity))
-                continue;
-            const owner = identity;
-            if (owner.cwd === cwdOwner && typeof owner.sessionId === "string" && owner.sessionId.length > 0) {
-                directories.push({ directory, scope: "session", cwdIdentity: cwdOwner, sessionId: owner.sessionId });
-            }
-        }
-    }
-    if (!directories.some(({ directory }) => directory === selectedSession)) {
-        directories.push({ directory: selectedSession, scope: "session", cwdIdentity: resolve(cwd), sessionId });
-    }
-    return directories;
-}
-/** Read-only activation eligibility, before global migration or any repository publication. */
-export function hasCwdMaterialization(cwd, repositoryRoot) {
-    const root = resolve(repositoryRoot);
-    const directory = cwdScopePaths(cwd, root).directory;
-    const [checkpoint, patches, meta] = captureOwnedFileBases([
-        join(directory, "checkpoint.json"), join(directory, "patches.jsonl"), join(directory, "meta.json"),
-    ], root);
-    if (checkpoint.content !== undefined)
-        return parseScopeStream(checkpoint.content, patches.content, "cwd", cwd, meta.content) !== undefined;
-    if (patches.content !== undefined)
-        throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
-    return false;
-}
-function checkpointNeedsIntentMigration(source) {
-    const checkpoint = JSON.parse(source);
-    if (migratePreIntentState(checkpoint) !== undefined)
-        return true;
-    return checkpoint !== null && typeof checkpoint === "object" && !Array.isArray(checkpoint)
-        && migratePreIntentState(checkpoint.state) !== undefined;
-}
-/** Detect predecessor snapshots, temporal envelopes, or pre-intents semantic states without mutating the store. */
-export function hasLegacyStateSources(cwd, sessionId, repositoryRoot, sessionKey = sessionId) {
-    const root = resolve(repositoryRoot);
-    return migrationDirectories(cwd, sessionId, root, sessionKey).some(({ directory, scope }) => {
-        const checkpointPath = join(directory, "checkpoint.json");
-        if (lstatSync(checkpointPath, { throwIfNoEntry: false }) === undefined)
-            return false;
-        try {
-            if (checkpointNeedsIntentMigration(readFileSync(checkpointPath, "utf8")))
-                return true;
-            const meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
-            if (meta === null || typeof meta !== "object" || !("temporal" in meta))
-                return true;
-            return scope === "session"
-                && lstatSync(join(directory, "runtime.json"), { throwIfNoEntry: false }) === undefined
-                && ("identity" in meta || "lineage" in meta);
-        }
-        catch {
-            return true;
-        }
-    });
-}
-/** Plan from current scope snapshots only; old explanatory journals are never replay input. */
-export function planLegacyStorageMigration(cwd, sessionId, repositoryRoot, _origin, sessionKey = sessionId) {
-    const root = resolve(repositoryRoot);
-    const directories = migrationDirectories(cwd, sessionId, root, sessionKey);
-    const paths = directories.flatMap(({ directory, scope }) => [
-        join(directory, "checkpoint.json"), join(directory, "patches.jsonl"), join(directory, "meta.json"),
-        ...(scope === "session" ? [join(directory, "config.json"), join(directory, "runtime.json")] : []),
-    ]);
-    const bases = captureOwnedFileBases(paths, root);
-    const byPath = new Map(bases.map((base) => [base.path, base]));
-    const updates = [];
-    const scopes = [];
-    for (const { scope, directory, cwdIdentity, sessionId: ownedSessionId } of directories) {
-        const checkpoint = byPath.get(join(directory, "checkpoint.json"));
-        const patches = byPath.get(join(directory, "patches.jsonl"));
-        const meta = byPath.get(join(directory, "meta.json"));
-        if (checkpoint.content !== undefined) {
-            const stream = parseScopeStream(checkpoint.content, patches.content, scope, scope === "cwd" ? cwdIdentity : undefined, meta.content);
-            const source = serializeScopeStream(stream, scope, scope === "cwd" ? cwdIdentity : undefined);
-            const metadata = serializeScopeMetadata(undefined, stream, scope, scope === "cwd" ? cwdIdentity : undefined, meta.content);
-            const cohortUpdates = [
-                ...(checkpoint.content === source.checkpoint ? [] : [{ path: checkpoint.path, content: source.checkpoint }]),
-                ...(patches.content === source.patches ? [] : [{ path: patches.path, content: source.patches }]),
-                ...(meta.content === metadata ? [] : [{ path: meta.path, content: metadata }]),
-            ];
-            if (scope === "session") {
-                const config = byPath.get(join(directory, "config.json"));
-                const runtimeFile = byPath.get(join(directory, "runtime.json"));
-                const runtime = parseSessionRuntime(config.content, runtimeFile.content, cwdIdentity, ownedSessionId, meta.content);
-                if (runtime !== undefined) {
-                    const serialized = serializeSessionRuntime(runtime, cwdIdentity, ownedSessionId);
-                    if (runtimeFile.content !== serialized.runtime)
-                        cohortUpdates.push({ path: runtimeFile.path, content: serialized.runtime });
-                }
-            }
-            if (cohortUpdates.length > 0) {
-                if (!scopes.includes(scope))
-                    scopes.push(scope);
-                updates.push(...cohortUpdates);
-            }
-            continue;
-        }
-        if (patches.content !== undefined)
-            throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
-    }
-    return { bases, updates, scopes };
-}

package/node_modules/@llblab/pi-state-flow/dist/lib/publication.d.ts

@@ -1,86 +0,0 @@
-export type RemotePublicationMode = "off" | "turn-end" | "transition";
-export interface RemotePublicationDestination {
-    gitCommonDir: string;
-    remote: string;
-    ref: string;
-}
-export interface RemotePublicationPolicy {
-    mode: RemotePublicationMode;
-    migratedLegacyDefault: boolean;
-}
-export interface RemotePublicationPolicyDocument {
-    version: 1;
-    mode: RemotePublicationMode;
-}
-/** Missing policy on an existing runtime preserves 0.4 synchronous behavior. */
-export declare function resolveRemotePublicationPolicy(value: unknown, options: {
-    legacyRuntime: boolean;
-}): RemotePublicationPolicy;
-export declare function parseRemotePublicationPolicyDocument(value: unknown, options: {
-    legacyRuntime: boolean;
-}): RemotePublicationPolicy;
-export declare function serializeRemotePublicationPolicyDocument(policy: RemotePublicationPolicy): RemotePublicationPolicyDocument;
-export declare function remotePublicationDestinationKey(destination: RemotePublicationDestination): string;
-export type PublicationQueueStatus = "pending" | "pushing" | "failed";
-export interface PublicationQueueState {
-    version: 1;
-    destination: RemotePublicationDestination;
-    target: string;
-    confirmed?: string;
-    status: PublicationQueueStatus;
-    attempt: number;
-    error?: string;
-}
-export type CommitAncestor = (ancestor: string, descendant: string) => boolean;
-export declare function createPublicationQueue(destination: RemotePublicationDestination, target: string): PublicationQueueState;
-export interface PublicationCoalesceObserver {
-    /** Called with the retired record when a journal lineage rewrite orphans its target. */
-    onDivergedLineage?: (previous: PublicationQueueState) => void;
-}
-export declare function coalescePublicationTarget(state: PublicationQueueState, destination: RemotePublicationDestination, target: string, isAncestor: CommitAncestor, observer?: PublicationCoalesceObserver): PublicationQueueState;
-export declare function parsePublicationQueue(content: string): PublicationQueueState;
-export declare function serializePublicationQueue(state: PublicationQueueState): string;
-export declare function beginPublicationAttempt(state: PublicationQueueState): PublicationQueueState;
-export declare function failPublicationAttempt(state: PublicationQueueState, error: string): PublicationQueueState;
-export declare function confirmPublicationTarget(state: PublicationQueueState, pushed: string, isAncestor: CommitAncestor): PublicationQueueState | undefined;
-/** A recovered pushing state is unconfirmed and safely retryable after restart. */
-export declare function recoverPublicationQueue(state: PublicationQueueState): PublicationQueueState;
-export declare function validatePublicationQueue(value: unknown): asserts value is PublicationQueueState;
-export declare function publicationQueuePath(destination: RemotePublicationDestination): string;
-export interface PublicationWorkerLease {
-    path: string;
-    token: string;
-    release(): void;
-}
-export declare function acquirePublicationWorkerLease(queuePath: string): PublicationWorkerLease | undefined;
-export declare function loadPublicationQueue(path: string): PublicationQueueState | undefined;
-export declare function removePublicationQueue(path: string, expected: PublicationQueueState): void;
-export interface PublicationQueueReceipt {
-    previous?: PublicationQueueState;
-    current: PublicationQueueState;
-}
-export declare function savePublicationQueue(path: string, state: PublicationQueueState, expected?: PublicationQueueState): PublicationQueueReceipt;
-export type PublicationPush = (state: Readonly<PublicationQueueState>) => Promise<void>;
-export interface PublicationWorkerResult {
-    attempted: PublicationQueueState;
-    next?: PublicationQueueState;
-}
-/** Execute one immutable target attempt; persistence/CAS remains the caller's responsibility. */
-export declare function runPublicationWorker(state: PublicationQueueState, push: PublicationPush, current: () => PublicationQueueState, isAncestor: CommitAncestor): Promise<PublicationWorkerResult>;
-export interface PublicationWorkerControllerPorts {
-    resolveDestination(): RemotePublicationDestination | undefined;
-    isAncestor(ancestor: string, descendant: string): boolean;
-    push(destination: RemotePublicationDestination, target: string, signal: AbortSignal): Promise<void>;
-    onDiverged(previous: PublicationQueueState, target: string): void;
-}
-/** Own durable queue coalescing, worker leases, retries, generation fencing, and bounded shutdown. */
-export declare class PublicationWorkerController {
-    private readonly active;
-    private readonly ports;
-    private stopped;
-    private shutdownPromise;
-    constructor(ports: PublicationWorkerControllerPorts);
-    enqueue(target: string): void;
-    launch(): void;
-    shutdown(waitMs: number): Promise<boolean>;
-}