@hassangameryt/freeflow 0.1.0 → 0.3.0

package/router/dist/evidence/failure-contracts.d.ts

@@ -0,0 +1,27 @@
+import type { EvidenceLineage, EvidencePacket, EvidencePersistence, FailureExecutionStatus, FailureRoutedResult, PreserveMode, RouterFailureKind, RoutingStatus, ToolStatus } from "../config/types.js";
+export type FailureOperationKind = "transform";
+export interface FailureResultOptions {
+    kind: RouterFailureKind;
+    operation: FailureOperationKind;
+    message: string;
+    preserve?: PreserveMode;
+    executionStatus?: FailureExecutionStatus;
+    toolStatus?: ToolStatus;
+    routingStatus?: RoutingStatus;
+    routingReason?: string;
+    persistence?: EvidencePersistence;
+    recordId?: string;
+    outputId?: string;
+    lineage?: EvidenceLineage;
+    evidence?: EvidencePacket[];
+    decisionSeed?: string;
+}
+export type TransformFailureOptions = Omit<FailureResultOptions, "kind" | "operation" | "executionStatus">;
+export type StorageFailureOptions = Omit<FailureResultOptions, "kind" | "operation" | "executionStatus">;
+export declare function storageFailure(options: StorageFailureOptions): FailureRoutedResult;
+export declare function scriptTransformDisabledFailure(options: TransformFailureOptions): FailureRoutedResult;
+export declare function transformAdapterUnavailableFailure(options: TransformFailureOptions): FailureRoutedResult;
+export declare function transformSourceUnavailableFailure(options: TransformFailureOptions): FailureRoutedResult;
+export declare function transformValidationFailure(options: TransformFailureOptions): FailureRoutedResult;
+export declare function transformExecutionFailure(options: TransformFailureOptions): FailureRoutedResult;
+export declare function createFailureResult(options: FailureResultOptions): FailureRoutedResult;

package/router/dist/evidence/failure-contracts.js

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+const DEFAULT_PRESERVE = "important";
+export function storageFailure(options) {
+    return createFailureResult({
+        toolStatus: "error",
+        routingStatus: "failed",
+        ...options,
+        kind: "storage_failure",
+        operation: "transform",
+        executionStatus: "failed",
+        persistence: options.persistence ?? noPersistence(),
+    });
+}
+export function scriptTransformDisabledFailure(options) {
+    return createFailureResult({
+        ...options,
+        kind: "script_transform_disabled",
+        operation: "transform",
+        executionStatus: "unavailable",
+    });
+}
+export function transformAdapterUnavailableFailure(options) {
+    return createFailureResult({
+        ...options,
+        kind: "adapter_unavailable",
+        operation: "transform",
+        executionStatus: "unavailable",
+    });
+}
+export function transformSourceUnavailableFailure(options) {
+    return createFailureResult({
+        ...options,
+        kind: "transform_source_unavailable",
+        operation: "transform",
+        executionStatus: "unavailable",
+    });
+}
+export function transformValidationFailure(options) {
+    return createFailureResult({
+        ...options,
+        kind: "transform_validation_failure",
+        operation: "transform",
+        executionStatus: "rejected",
+    });
+}
+export function transformExecutionFailure(options) {
+    return createFailureResult({
+        ...options,
+        kind: "transform_execution_failure",
+        operation: "transform",
+        executionStatus: "failed",
+    });
+}
+export function createFailureResult(options) {
+    const preserve = options.preserve ?? DEFAULT_PRESERVE;
+    const persistence = normalizePersistence(options.persistence, options.outputId);
+    const routingStatus = options.routingStatus ?? "failed";
+    const recovery = recoveryHintForPersistence(persistence);
+    const executionStatus = options.executionStatus ?? defaultExecutionStatus(options.kind);
+    const result = {
+        toolStatus: options.toolStatus ?? "ok",
+        decisionId: failureDecisionId(options),
+        preserve,
+        routing: {
+            status: routingStatus,
+            route: "transform",
+            reason: options.routingReason ?? failureReason(options.kind, options.operation, options.message, persistence),
+        },
+        failure: {
+            kind: options.kind,
+            message: options.message,
+        },
+        persistence,
+        recovery,
+        transformExecution: executionFailure(executionStatus, options.kind, options.message),
+    };
+    if (options.recordId !== undefined) {
+        result.recordId = options.recordId;
+    }
+    if (options.outputId !== undefined) {
+        result.outputId = options.outputId;
+    }
+    if (options.lineage !== undefined) {
+        result.lineage = options.lineage;
+    }
+    if (options.evidence !== undefined) {
+        result.evidence = options.evidence;
+    }
+    return result;
+}
+function executionFailure(status, failureKind, message) {
+    return { status, failureKind, message };
+}
+function normalizePersistence(persistence, outputId) {
+    const candidate = persistence ?? noPersistence();
+    if (candidate.recoverability !== "exact" && candidate.recoverability !== "redacted") {
+        return candidate;
+    }
+    const recoveryOutputId = candidate.recoveryOutputId ?? candidate.outputId ?? outputId;
+    if (recoveryOutputId === undefined) {
+        return noPersistence();
+    }
+    return {
+        ...candidate,
+        recoveryOutputId,
+        ...(candidate.outputId !== undefined ? { outputId: candidate.outputId } : {}),
+    };
+}
+function noPersistence() {
+    return { status: "not_persisted", recoverability: "none" };
+}
+function recoveryHintForPersistence(persistence) {
+    const recoveryOutputId = persistence.recoveryOutputId ?? persistence.outputId;
+    if (persistence.recoverability === "exact" && recoveryOutputId !== undefined) {
+        return {
+            how: `Use freeflow_search with source.kind=vault and outputId=${recoveryOutputId} to recover exact transformed content.`,
+            outputId: recoveryOutputId,
+        };
+    }
+    if (persistence.recoverability === "redacted" && recoveryOutputId !== undefined) {
+        return {
+            how: `Use freeflow_search with source.kind=vault and outputId=${recoveryOutputId} to recover redacted persisted content. Exact raw recovery is unavailable.`,
+            outputId: recoveryOutputId,
+        };
+    }
+    if (persistence.recoverability === "metadata_only") {
+        return {
+            how: "Only metadata was persisted for this failure. No raw content stream is recoverable.",
+        };
+    }
+    return {
+        how: "No content was persisted for this failure. Recovery is unavailable.",
+    };
+}
+function defaultExecutionStatus(kind) {
+    if (kind === "adapter_unavailable" || kind === "transform_source_unavailable" || kind === "script_transform_disabled") {
+        return "unavailable";
+    }
+    if (kind === "transform_validation_failure") {
+        return "rejected";
+    }
+    return "failed";
+}
+function failureReason(kind, operation, message, persistence) {
+    return `${operation} failure kind=${kind}: ${message} persistence.status=${persistence.status}; recoverability=${persistence.recoverability}.`;
+}
+function failureDecisionId(options) {
+    return `ffdec_${hash(JSON.stringify([
+        "failure",
+        options.kind,
+        options.operation,
+        options.recordId ?? null,
+        options.outputId ?? null,
+        options.decisionSeed ?? null,
+        options.message,
+    ])).slice(0, 16)}`;
+}
+function hash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}

package/router/dist/evidence/line-ranges.d.ts

@@ -0,0 +1,22 @@
+export interface ExactLineRangeInput {
+    start: number;
+    end: number;
+}
+export interface ExactLineRange {
+    start: number;
+    end: number;
+}
+export interface ResolveExactLineRangeOptions {
+    requested: ExactLineRangeInput;
+    lineCount: number;
+    availableLabel: string;
+    invalidReason: string;
+}
+export type ResolveExactLineRangeResult = {
+    ok: true;
+    range: ExactLineRange;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function resolveExactLineRange(options: ResolveExactLineRangeOptions): ResolveExactLineRangeResult;

package/router/dist/evidence/line-ranges.js

@@ -0,0 +1,22 @@
+export function resolveExactLineRange(options) {
+    const { requested, lineCount, availableLabel, invalidReason } = options;
+    if (!isValidExactLineRange(requested)) {
+        return { ok: false, reason: invalidReason };
+    }
+    if (requested.start > lineCount) {
+        return {
+            ok: false,
+            reason: `Requested lineRange start ${requested.start} is outside ${availableLabel} 1-${lineCount}.`,
+        };
+    }
+    if (requested.end > lineCount) {
+        return {
+            ok: false,
+            reason: `Requested lineRange end ${requested.end} is outside ${availableLabel} 1-${lineCount}.`,
+        };
+    }
+    return { ok: true, range: { start: requested.start, end: requested.end } };
+}
+function isValidExactLineRange(range) {
+    return Number.isInteger(range.start) && Number.isInteger(range.end) && range.start >= 1 && range.end >= range.start;
+}

package/router/dist/experiments/local-index.d.ts

@@ -0,0 +1,58 @@
+export interface ExperimentalLocalIndexOptions {
+    root: string;
+    cacheRoot?: string;
+    generatedPathGlobs?: readonly string[];
+}
+export interface ExperimentalIndexLoadResult {
+    mode: ExperimentalIndexLoadMode;
+    index: ExperimentalRepoIndex;
+    cachePath: string;
+    buildMs: number;
+    refreshReason?: string;
+}
+export type ExperimentalIndexLoadMode = "cold-built" | "warm-loaded" | "stale-refreshed";
+export interface ExperimentalRepoIndex {
+    version: 1;
+    root: string;
+    builtAt: string;
+    files: Record<string, ExperimentalIndexedFile>;
+    chunks: ExperimentalIndexedChunk[];
+    tokenDocumentFrequency: Record<string, number>;
+    averageChunkTokens: number;
+    cachePath: string;
+}
+export interface ExperimentalIndexedFile {
+    path: string;
+    hashSha256: string;
+    sizeBytes: number;
+    lineCount: number;
+    chunkIds: number[];
+}
+export interface ExperimentalIndexedChunk {
+    id: number;
+    path: string;
+    startLine: number;
+    endLine: number;
+    kind: "section" | "window";
+    text: string;
+    tokens: string[];
+    tokenCounts: Record<string, number>;
+    heading?: string;
+}
+export interface ExperimentalIndexQueryOptions {
+    topK?: number;
+}
+export interface ExperimentalIndexCandidate {
+    path: string;
+    lines: string;
+    excerpt: string;
+    score: number;
+    reason: string;
+    chunkKind: ExperimentalIndexedChunk["kind"];
+    hashSha256: string;
+    contextBytes: number;
+}
+export declare function defaultExperimentalIndexCacheRoot(): string;
+export declare function experimentalIndexCachePath(options: ExperimentalLocalIndexOptions): Promise<string>;
+export declare function buildOrLoadExperimentalRepoIndex(options: ExperimentalLocalIndexOptions): Promise<ExperimentalIndexLoadResult>;
+export declare function queryExperimentalRepoIndex(index: ExperimentalRepoIndex, query: string, options?: ExperimentalIndexQueryOptions): ExperimentalIndexCandidate[];