Protected Span Preservation in FreeLLMAPI: How It Safeguards Critical Prompt Content

Protected span preservation ensures essential portions of a prompt remain unchanged during aggressive token reduction by detecting marked regions, merging overlapping intervals, and reinserting them verbatim after compression.

FreeLLMAPI compresses prompts before transmitting them to language model providers to stay within token limits and minimize latency. During this process, protected span preservation acts as a safety mechanism that shields designated content from any modification. This article explains how this feature works based on the implementation in the tashfeenahmed/freellmapi repository.

What Are Protected Spans?

Protected spans are specific regions of a prompt that must remain exactly unchanged throughout the compression pipeline. Common examples include:

• System messages that define model behavior and constraints
• User-provided instructions requiring verbatim preservation, such as JSON schemas or function definitions
• Structural markers like {{START}} / {{END}} delimiters or custom tags such as <protected>...</protected>

The preservation system guarantees these regions survive even the most aggressive compression strategies.

Core Implementation Architecture

The protected span preservation logic resides in server/src/services/compression/preservation.ts. This module provides the foundation for three critical properties: detection, normalization, and reintegration.

Step 1: Detecting Protected Regions

The system scans prompts for protected-span markers using configurable delimiters defined in compression/config.ts. The findProtectedSpans() function records exact character offsets for each protected region.

// Internals: detecting protected spans (simplified)
import { findProtectedSpans } from './preservation';

const prompt = `
<protected>
You are a helpful assistant that must always respond in JSON.
{
  "schema": { "type": "object", "properties": { "answer": { "type": "string" } } }
}
</protected>

User: Explain the difference between GPT-4 and Claude.
`;

const rawSpans = findProtectedSpans(prompt);
// rawSpans = [{ start: 1, end: 215 }, { start: 190, end: 260 }]  // overlapping detected

Step 2: Merging Overlapping Intervals

When protected regions overlap or nest, the mergeSpans() function normalizes them into a minimal set of disjoint intervals. This prevents duplicate preservation and simplifies downstream processing.

// Internals: merging overlapping spans
import { mergeSpans } from './preservation';

const merged = mergeSpans(rawSpans);
// merged = [{ start: 1, end: 260 }]  // single, non-overlapping span

The algorithm sorts spans by offset and coalesces any intersecting intervals, yielding normalized bounds that pipeline.ts uses for reintegration.

Step 3: Reintegrating Preserved Content

The pipeline.ts orchestrator removes tokens from unprotected portions only, then stitches preserved spans back using the normalized intervals. This design ensures compression aggressiveness never compromises protected content.

Key Guarantees of Protected Span Preservation

The implementation in preservation.ts provides two essential properties:

1. Idempotence — Running the compressor repeatedly does not alter protected spans or shift their positions. The system tracks and re-inserts unchanged content after each compression pass.

2. Safety — Token-budget reducers including deduplication, JSON compaction, and relevance-based trimming cannot delete or modify protected regions. This prevents breaking system-level contracts or user-defined constraints.

Verification occurs in compression.test.ts, where the unit test "finds and merges overlapping protected spans idempotently" validates correct behavior under repeated execution.

Practical Usage Example

The high-level compressPrompt() API enables protected span preservation through a single configuration flag:

// Example: marking and preserving a protected span
const prompt = `
<protected>
You are a helpful assistant that must always respond in JSON.
{
  "schema": { "type": "object", "properties": { "answer": { "type": "string" } } }
}
</protected>

User: Explain the difference between GPT-4 and Claude.
`;

import { compressPrompt } from '@freellmapi/compression';

const compressed = await compressPrompt(prompt, {
  maxTokens: 512,               // target token budget
  preserveProtectedSpans: true, // enable protected-span preservation
});

// `compressed` contains the exact protected block above,
// while the remaining prompt may be trimmed or compacted

Source File Reference

File	Role
server/src/services/compression/preservation.ts	Core logic for detecting, normalizing, and preserving protected spans
server/src/services/compression/pipeline.ts	Orchestrates compression; integrates preservation step
server/src/services/compression/config.ts	Defines default protected-span delimiters and settings
server/src/__tests__/services/compression.test.ts	Validates detection, merging, and idempotence

Summary

• Protected span preservation guarantees essential prompt content survives aggressive token reduction in FreeLLMAPI
• The preservation.ts module detects marked regions using configurable delimiters from config.ts
• Overlapping spans merge into disjoint intervals via mergeSpans() to simplify reintegration
• pipeline.ts removes tokens from unprotected areas only, then reinserts preserved content unchanged
• Idempotence and safety are enforced by design and verified in compression.test.ts

Frequently Asked Questions

How do I mark content as protected in a FreeLLMAPI prompt?

Wrap critical content in <protected>...</protected> tags or custom delimiters defined in compression/config.ts. The findProtectedSpans() function in preservation.ts detects these markers automatically and records their character offsets for preservation.

Does protected span preservation reduce compression effectiveness?

Only minimally. The system targets unprotected regions for aggressive reduction while preserving exact byte content of protected spans. Since protected regions typically represent small fractions of total prompt length, significant token savings remain achievable.

What happens if two protected spans overlap?

The mergeSpans() algorithm in preservation.ts sorts intervals by start position and coalesces overlapping or adjacent regions into a single continuous span. This normalization prevents duplicate handling and ensures clean reintegration by pipeline.ts.

Is the preservation behavior tested for repeated compression runs?

Yes. The test suite in compression.test.ts specifically validates idempotence with the test case "finds and merges overlapping protected spans idempotently," confirming that multiple compression passes produce identical protected span handling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}