@deftai/directive-core 0.95.0 → 0.96.0

package/dist/cache/archive.d.ts

@@ -0,0 +1,134 @@
+import { ProjectionContainmentError } from "../fs/projection-containment.js";
+import { type Clock } from "./time.js";
+export { ProjectionContainmentError as CacheArchiveContainmentError };
+/** Archive age default matches TTL prune window but is a separate concept (#1137). */
+export declare const DEFAULT_ARCHIVE_OLDER_THAN_DAYS = 30;
+export declare const ARCHIVE_SOURCE_GITHUB_ISSUE = "github-issue";
+export declare const ARCHIVED_ROOT_SEGMENT = "archived";
+export declare const ARCHIVE_META_FILENAME = "archive-meta.json";
+export interface ArchiveMeta {
+    archived_at: string;
+    reason: string;
+    source_path: string;
+    key: string;
+    source: string;
+    pre_archive_decision?: string | null;
+    closed_at?: string | null;
+    age_basis?: string;
+}
+export type ArchiveSkipReason = "not-closed" | "too-recent" | "open-lifecycle-scope" | "non-terminal-decision" | "missing-raw" | "invalid-key" | "already-archived";
+export interface ArchiveCandidate {
+    source: string;
+    key: string;
+    liveDir: string;
+    archiveDir: string;
+    closedAt: string | null;
+    ageBasis: string;
+    ageMs: number;
+    preArchiveDecision: string | null;
+}
+export interface ArchiveSkip {
+    source: string;
+    key: string;
+    reason: ArchiveSkipReason;
+    detail?: string;
+}
+export interface ArchiveClosedResult {
+    dryRun: boolean;
+    olderThanDays: number;
+    source: string;
+    repo: string | null;
+    archived: ArchiveCandidate[];
+    skipped: ArchiveSkip[];
+    archivedCount: number;
+    skippedCount: number;
+}
+export interface ArchivedEntry {
+    source: string;
+    key: string;
+    archiveDir: string;
+    archivedAt: string;
+    meta: ArchiveMeta;
+}
+export interface ArchiveListResult {
+    entries: ArchivedEntry[];
+    count: number;
+    source: string;
+    repo: string | null;
+}
+export interface RestoreResult {
+    source: string;
+    key: string;
+    status: "restored" | "already-live" | "missing" | "conflict";
+    liveDir: string;
+    archiveDir: string;
+    detail?: string;
+}
+/** Live entry dir for a github-issue key. */
+export declare function liveEntryDir(source: string, key: string, cacheRoot: string): string;
+/** Archived entry dir: `.deft-cache/archived/<source>/<owner>/<repo>/<N>/`. */
+export declare function archivedEntryDir(source: string, key: string, cacheRoot: string): string;
+/**
+ * Open-lifecycle protection set: preferred keys are `owner/repo#N`.
+ * Bare `#N` keys are also recorded when the plan URI has no repo (conservative).
+ */
+export declare function openLifecycleReferencedKeys(projectRoot: string): ReadonlySet<string>;
+/** True when cache key `owner/repo/N` is protected by open lifecycle refs. */
+export declare function isLifecycleProtected(cacheKey: string, protectedKeys: ReadonlySet<string>): boolean;
+/**
+ * Resolve closed age basis: `closed_at` from raw, else `meta.fetched_at`, else
+ * meta.json mtime (#1137).
+ */
+export declare function resolveClosedAge(raw: Record<string, unknown>, meta: Record<string, unknown> | null, metaPath: string, now: Date): {
+    closedAt: string | null;
+    ageBasis: string;
+    ageMs: number;
+};
+export interface ArchiveClosedOptions {
+    olderThanDays?: number;
+    source?: string;
+    repo?: string | null;
+    dryRun?: boolean;
+    cacheRoot?: string;
+    projectRoot?: string;
+    /** Optional map of `owner/repo#N` or `N` → latest decision string. */
+    latestDecisions?: ReadonlyMap<string, string> | null;
+    /** When true, only archive reject / mark-duplicate latest decisions. */
+    terminalDecisionOnly?: boolean;
+    /** Override protected issue set (tests); default scans open lifecycle. */
+    protectedIssueNumbers?: ReadonlySet<number> | null;
+    /** Override protected keys `owner/repo#N` / `#N` (preferred multi-repo form). */
+    protectedKeys?: ReadonlySet<string> | null;
+    reason?: string;
+    clock?: Clock;
+}
+/**
+ * Archive closed github-issue cache entries older than the threshold.
+ * Skips (does not half-move) entries still referenced by open lifecycle scopes.
+ */
+export declare function archiveClosedEntries(options?: ArchiveClosedOptions): ArchiveClosedResult;
+export interface ArchiveListOptions {
+    source?: string;
+    repo?: string | null;
+    since?: string | null;
+    limit?: number | null;
+    cacheRoot?: string;
+}
+/** List archived entries newest `archived_at` first. */
+export declare function listArchivedEntries(options?: ArchiveListOptions): ArchiveListResult;
+export interface RestoreFromArchiveOptions {
+    source?: string;
+    key?: string;
+    issue?: number;
+    repo?: string | null;
+    force?: boolean;
+    cacheRoot?: string;
+    clock?: Clock;
+}
+/**
+ * Move an archived entry back to the live cache path.
+ * Idempotent no-op when already live with identical raw.json.
+ * Refuse when live exists with different content unless force.
+ */
+export declare function restoreFromArchive(options?: RestoreFromArchiveOptions): RestoreResult;
+//# sourceMappingURL=archive.d.ts.map