@hassangameryt/freeflow 0.4.0 → 0.6.0

package/router/dist/evidence/evidence.js

@@ -1,200 +0,0 @@
-export const DEFAULT_MAX_IMPORTANT_LINES = 8;
-export const DEFAULT_MAX_IMPORTANT_EXCERPT_BYTES = 8 * 1024;
-export const DEFAULT_MAX_IMPORTANT_LINE_BYTES = 2 * 1024;
-export const TRUNCATION_MARKER = "… [truncated; recover exact output from vault]";
-export function assembleImportantLines(options) {
-  const caps = normalizeCaps(options.caps);
-  const sourceLineCount = countLines(options.sourceText);
-  const sortedEntries = uniqueSortedEntries(options.entries).slice(0, caps.maxLines);
-  const sourceEntries = lineEntries(options.sourceText);
-  if (sortedEntries.length === 0) {
-    return {
-      importantLines: [],
-      fidelity: "exact",
-      compressed: sourceLineCount > 0,
-      selectedLineCount: 0,
-      sourceLineCount,
-    };
-  }
-  const selectedLineNumbers = new Set(sortedEntries.map((entry) => entry.lineNumber));
-  const omittedSelectedEntries = uniqueSortedEntries(options.entries).length > sortedEntries.length;
-  const omittedSourceEntries = sourceEntries.some((entry) => !selectedLineNumbers.has(entry.lineNumber));
-  const groups = contiguousGroups(sortedEntries);
-  const importantLines = [];
-  let remainingBytes = caps.maxExcerptBytes;
-  let lossy = omittedSelectedEntries;
-  let selectedLineCount = 0;
-  for (const group of groups) {
-    if (remainingBytes <= 0) {
-      lossy = true;
-      break;
-    }
-    const built = buildBoundedExcerpt(group, remainingBytes, caps.maxLineBytes);
-    if (built.excerpt.length === 0 && group.length > 0) {
-      lossy = true;
-      break;
-    }
-    importantLines.push({
-      stream: options.stream,
-      lines: lineRange(built.entries),
-      excerpt: built.excerpt,
-    });
-    remainingBytes -= byteLength(built.excerpt);
-    selectedLineCount += built.selectedLineCount;
-    lossy = lossy || built.lossy;
-  }
-  return {
-    importantLines,
-    fidelity: lossy ? "lossy" : "exact",
-    compressed: lossy || omittedSourceEntries,
-    selectedLineCount,
-    sourceLineCount,
-  };
-}
-export function assembleTextEvidence(options) {
-  const caps = normalizeCaps(options.caps);
-  const entries = lineEntries(options.text);
-  const sourceLineCount = entries.length;
-  if (entries.length === 0) {
-    return {
-      importantLines: [],
-      fidelity: "exact",
-      compressed: false,
-      selectedLineCount: 0,
-      sourceLineCount,
-    };
-  }
-  if (
-    entries.length <= caps.maxLines &&
-    byteLength(options.text) <= caps.maxExcerptBytes &&
-    entries.every((entry) => byteLength(entry.line) <= caps.maxLineBytes)
-  ) {
-    return {
-      importantLines: [
-        {
-          stream: options.stream,
-          lines: lineRange(entries),
-          excerpt: options.text,
-        },
-      ],
-      fidelity: "exact",
-      compressed: false,
-      selectedLineCount: entries.length,
-      sourceLineCount,
-    };
-  }
-  return assembleImportantLines({ stream: options.stream, entries, sourceText: options.text, caps });
-}
-export function lineEntries(text) {
-  return splitLines(text).map((line, index) => ({ line, lineNumber: index + 1 }));
-}
-export function nonEmptyLineEntries(text) {
-  return lineEntries(text).filter((entry) => entry.line.trim().length > 0);
-}
-export function splitLines(text) {
-  if (text.length === 0) {
-    return [];
-  }
-  return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
-}
-export function countLines(text) {
-  return splitLines(text).length;
-}
-export function byteLength(text) {
-  return Buffer.byteLength(text, "utf8");
-}
-function normalizeCaps(caps) {
-  return {
-    maxLines: caps?.maxLines ?? DEFAULT_MAX_IMPORTANT_LINES,
-    maxExcerptBytes: caps?.maxExcerptBytes ?? DEFAULT_MAX_IMPORTANT_EXCERPT_BYTES,
-    maxLineBytes: caps?.maxLineBytes ?? DEFAULT_MAX_IMPORTANT_LINE_BYTES,
-  };
-}
-function uniqueSortedEntries(entries) {
-  const byLineNumber = new Map();
-  for (const entry of entries) {
-    if (entry.lineNumber <= 0 || byLineNumber.has(entry.lineNumber)) {
-      continue;
-    }
-    byLineNumber.set(entry.lineNumber, entry);
-  }
-  return [...byLineNumber.values()].sort((a, b) => a.lineNumber - b.lineNumber);
-}
-function contiguousGroups(entries) {
-  const groups = [];
-  let current = [];
-  for (const entry of entries) {
-    const previous = current[current.length - 1];
-    if (!previous || entry.lineNumber === previous.lineNumber + 1) {
-      current.push(entry);
-      continue;
-    }
-    groups.push(current);
-    current = [entry];
-  }
-  if (current.length > 0) {
-    groups.push(current);
-  }
-  return groups;
-}
-function buildBoundedExcerpt(entries, maxExcerptBytes, maxLineBytes) {
-  const parts = [];
-  const includedEntries = [];
-  let remainingBytes = maxExcerptBytes;
-  let lossy = false;
-  let selectedLineCount = 0;
-  for (const entry of entries) {
-    const separatorBytes = parts.length === 0 ? 0 : 1;
-    const remainingForLine = remainingBytes - separatorBytes;
-    if (remainingForLine <= 0) {
-      lossy = true;
-      break;
-    }
-    const line = truncateLine(entry.line, Math.min(maxLineBytes, remainingForLine));
-    if (parts.length > 0) {
-      remainingBytes -= 1;
-    }
-    parts.push(line.text);
-    includedEntries.push(entry);
-    remainingBytes -= byteLength(line.text);
-    selectedLineCount += 1;
-    lossy = lossy || line.lossy;
-  }
-  return { excerpt: parts.join("\n"), entries: includedEntries, lossy, selectedLineCount };
-}
-function truncateLine(line, maxBytes) {
-  if (byteLength(line) <= maxBytes) {
-    return { text: line, lossy: false };
-  }
-  if (maxBytes <= 0) {
-    return { text: "", lossy: true };
-  }
-  const markerBytes = byteLength(TRUNCATION_MARKER);
-  if (maxBytes <= markerBytes) {
-    return { text: truncateUtf8(TRUNCATION_MARKER, maxBytes), lossy: true };
-  }
-  return {
-    text: `${truncateUtf8(line, maxBytes - markerBytes)}${TRUNCATION_MARKER}`,
-    lossy: true,
-  };
-}
-function truncateUtf8(text, maxBytes) {
-  if (byteLength(text) <= maxBytes) {
-    return text;
-  }
-  let end = Math.min(text.length, maxBytes);
-  while (end > 0 && byteLength(text.slice(0, end)) > maxBytes) {
-    end -= 1;
-  }
-  return text.slice(0, end);
-}
-function lineRange(entries) {
-  const first = entries[0];
-  const last = entries[entries.length - 1];
-  if (!first || !last) {
-    return "1-1";
-  }
-  return first.lineNumber === last.lineNumber
-    ? `${first.lineNumber}-${first.lineNumber}`
-    : `${first.lineNumber}-${last.lineNumber}`;
-}

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

@@ -1,37 +0,0 @@
-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

@@ -1,166 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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

@@ -1,64 +0,0 @@
-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[];