harnery 0.34.1 → 0.36.0

package/dist/core/storage/maintenance.d.ts

@@ -0,0 +1,125 @@
+import type { HarneryStorageCatalog } from "./catalog.js";
+export declare const HARNERY_MAINTENANCE_TRANSACTION_SCHEMA: "harnery.storage-maintenance-transaction/v1";
+export declare const HARNERY_MAINTENANCE_RECEIPT_SCHEMA: "harnery.storage-maintenance-receipt/v1";
+export declare const HARNERY_MAINTENANCE_CURSOR_SCHEMA: "harnery.storage-maintenance-cursor/v1";
+export declare const HARNERY_MAINTENANCE_PRESSURE_SCHEMA: "harnery.storage-pressure/v1";
+export interface HarneryMaintenanceBudget {
+    max_duration_ms: number;
+    max_files: number;
+    max_bytes: number;
+}
+export interface HarneryStoragePressureFamily {
+    family_id: string;
+    logical_bytes: number;
+    regular_files: number;
+    needs_maintenance: boolean;
+    observed_at: string;
+}
+export interface HarneryStoragePressureSummary {
+    schema: typeof HARNERY_MAINTENANCE_PRESSURE_SCHEMA;
+    captured_at: string;
+    families: readonly HarneryStoragePressureFamily[];
+}
+export interface HarneryMaintenanceAction {
+    action_id: string;
+    family_id: string;
+    kind: string;
+    target_ref: string;
+    files: number;
+    bytes: number;
+    destructive: boolean;
+    /** Exact provider-owned destructive scope; generic destructive actions are never authorized. */
+    authorization_scope?: string;
+    /** Effective user/source retention policy frozen into the plan. */
+    effective_policy_fingerprint?: string;
+    expected_sha256?: string;
+    metadata?: Readonly<Record<string, string | number | boolean>>;
+}
+export interface HarneryMaintenanceProviderPlan {
+    actions: readonly HarneryMaintenanceAction[];
+    next_cursor?: string;
+}
+export interface HarneryMaintenanceProvider {
+    family_id: string;
+    /** The sole destructive scope this provider may plan and apply. */
+    destructive_scope?: string;
+    budget?: Partial<HarneryMaintenanceBudget>;
+    plan(input: {
+        coord_root: string;
+        pressure: HarneryStoragePressureFamily;
+        cursor?: string;
+        budget: HarneryMaintenanceBudget;
+        now: Date;
+    }): HarneryMaintenanceProviderPlan | Promise<HarneryMaintenanceProviderPlan>;
+    apply(input: {
+        coord_root: string;
+        transaction_id: string;
+        action: HarneryMaintenanceAction;
+        now: Date;
+    }): HarneryMaintenanceMutation | Promise<HarneryMaintenanceMutation>;
+}
+export interface HarneryMaintenanceMutation {
+    outcome: "applied" | "already_applied" | "refused";
+    output_sha256?: string;
+    detail?: string;
+}
+export interface HarneryMaintenanceTransaction {
+    schema: typeof HARNERY_MAINTENANCE_TRANSACTION_SCHEMA;
+    transaction_id: string;
+    created_at: string;
+    updated_at: string;
+    state: "planned" | "running" | "committed" | "refused" | "failed";
+    dry_run: boolean;
+    catalog_policies: Readonly<Record<string, string>>;
+    effective_policy_fingerprints: Readonly<Record<string, string>>;
+    budget: HarneryMaintenanceBudget;
+    actions: readonly HarneryMaintenanceAction[];
+    next_cursors: Readonly<Record<string, string>>;
+    reason_codes: readonly string[];
+}
+export interface HarneryMaintenanceReceipt {
+    schema: typeof HARNERY_MAINTENANCE_RECEIPT_SCHEMA;
+    transaction_id: string;
+    action_id: string;
+    family_id: string;
+    action_sha256: string;
+    outcome: HarneryMaintenanceMutation["outcome"];
+    output_sha256?: string;
+    detail?: string;
+    committed_at: string;
+}
+export interface HarneryAutomaticMaintenanceResult {
+    ran: boolean;
+    reason: "disabled" | "no-pressure" | "fresh" | "contended" | "planned" | "committed";
+    transaction_id?: string;
+    actions: number;
+    files: number;
+    bytes: number;
+}
+export declare const DEFAULT_MAINTENANCE_BUDGET: HarneryMaintenanceBudget;
+export declare function planStorageMaintenance(catalog: HarneryStorageCatalog, providers: readonly HarneryMaintenanceProvider[], pressure: HarneryStoragePressureSummary, options?: {
+    now?: Date;
+    budget?: HarneryMaintenanceBudget;
+    family_id?: string;
+    persist?: boolean;
+    transaction_id?: string;
+}): Promise<HarneryMaintenanceTransaction>;
+export declare function executeStorageMaintenance(catalog: HarneryStorageCatalog, providers: readonly HarneryMaintenanceProvider[], transactionId: string, options: {
+    yes: boolean;
+    now?: Date;
+    authorize_structured_log_deletion?: boolean;
+}): Promise<HarneryMaintenanceTransaction>;
+export declare function runAutomaticMaintenanceSlice(catalog: HarneryStorageCatalog, providers: readonly HarneryMaintenanceProvider[], options?: {
+    now?: Date;
+    budget?: HarneryMaintenanceBudget;
+    execute?: boolean;
+}): Promise<HarneryAutomaticMaintenanceResult>;
+export declare function readMaintenanceTransaction(coordRoot: string, transactionId: string): HarneryMaintenanceTransaction;
+export declare function listMaintenanceTransactions(coordRoot: string): HarneryMaintenanceTransaction[];
+export declare function writePressureSummary(coordRoot: string, summary: HarneryStoragePressureSummary): void;
+export declare function readPressureSummary(coordRoot: string): HarneryStoragePressureSummary | undefined;
+export declare class HarneryMaintenanceError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+//# sourceMappingURL=maintenance.d.ts.map

package/dist/core/storage/maintenance.d.ts.map

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