trellis/dist/links/lifecycle.d.ts

Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications

/**
 * Ref Lifecycle — Rename Prompts & Stale Detection
 *
 * Handles the three-tier diagnostic model for wiki-link references:
 * - Resolved: target exists and resolves
 * - Stale (warning): target was renamed or deleted, known provenance
 * - Broken (error): target never existed
 *
 * On symbol rename → build a RefUpdateProposal for user confirmation.
 * On symbol delete → mark affected refs as stale (no file modification).
 *
 * @see TRL-14
 */
import type { RefIndex, RefSource, RefUpdateProposal, RefState } from './types.js';
export interface StaleRef {
    /** The entity ID that became stale */
    entityId: string;
    /** Why it became stale */
    reason: 'renamed' | 'deleted';
    /** The op hash that caused the staleness */
    causeOpHash?: string;
    /** For renames: the new name */
    newTarget?: string;
    /** Timestamp when it became stale */
    timestamp: string;
    /** Sources that reference this stale entity */
    sources: RefSource[];
}
/**
 * In-memory stale ref registry.
 * Maps entity ID → StaleRef.
 */
export declare class StaleRefRegistry {
    private staleRefs;
    /**
     * Mark an entity as stale due to rename or deletion.
     */
    markStale(entityId: string, reason: 'renamed' | 'deleted', sources: RefSource[], opts?: {
        causeOpHash?: string;
        newTarget?: string;
    }): StaleRef;
    /**
     * Remove stale status (e.g. after user accepts rename update).
     */
    clearStale(entityId: string): void;
    /**
     * Check if an entity is stale.
     */
    isStale(entityId: string): boolean;
    /**
     * Get stale info for an entity.
     */
    getStale(entityId: string): StaleRef | undefined;
    /**
     * Get all stale refs.
     */
    getAllStale(): StaleRef[];
    /**
     * Get stale refs filtered by reason.
     */
    getByReason(reason: 'renamed' | 'deleted'): StaleRef[];
}
/**
 * Build a RefUpdateProposal when a symbol is renamed.
 * Scans the ref index for all references to the old symbol name
 * and produces a list of rewrites.
 *
 * Does NOT modify any files — returns a proposal for user confirmation.
 */
export declare function buildRenameProposal(index: RefIndex, filePath: string, oldName: string, newName: string): RefUpdateProposal;
/**
 * Apply a RefUpdateProposal by rewriting files.
 * Reads each affected file, applies the rewrites, and writes back.
 *
 * Returns the list of files that were actually modified.
 */
export declare function applyRenameProposal(proposal: RefUpdateProposal, rootPath: string): string[];
/**
 * Handle a symbol deletion by marking all referencing refs as stale.
 * Does NOT modify any files.
 *
 * Returns the StaleRef entry for diagnostic display.
 */
export declare function handleSymbolDeletion(index: RefIndex, registry: StaleRefRegistry, filePath: string, symbolName: string, causeOpHash?: string): StaleRef | null;
/**
 * Handle a file deletion by marking all refs to that file (and its symbols) as stale.
 */
export declare function handleFileDeletion(index: RefIndex, registry: StaleRefRegistry, filePath: string, causeOpHash?: string): StaleRef | null;
export type RefDiagnostic = {
    entityId: string;
    state: RefState;
    source: RefSource;
    message: string;
};
/**
 * Produce diagnostics for all refs in the index.
 * Combines stale registry info with broken ref detection.
 */
export declare function getDiagnostics(index: RefIndex, registry: StaleRefRegistry, resolvedEntityIds: Set<string>): RefDiagnostic[];
import type { SemanticPatch } from '../semantic/types.js';
export interface LifecycleEvent {
    type: 'rename-proposal' | 'stale-detected';
    filePath: string;
    proposal?: RefUpdateProposal;
    staleRef?: StaleRef;
}
/**
 * Process semantic patches and produce lifecycle events.
 * This is the main integration point — call this when sdiff detects changes.
 */
export declare function processSemanticPatches(patches: SemanticPatch[], filePath: string, index: RefIndex, registry: StaleRefRegistry, causeOpHash?: string): LifecycleEvent[];
//# sourceMappingURL=lifecycle.d.ts.map