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

> Learn how FreeLLMAPI's protected span preservation safeguards critical prompt content. Discover how it ensures essential parts of your prompt remain unchanged during compression.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: deep-dive
- Published: 2026-08-28

---

**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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/compression/config.ts). The `findProtectedSpans()` function records exact character offsets for each protected region.

```typescript
// 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.

```typescript
// 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`](https://github.com/tashfeenahmed/freellmapi/blob/main/pipeline.ts) uses for reintegration.

### Step 3: Reintegrating Preserved Content

The [`pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```typescript
// 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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/preservation.ts) | Core logic for detecting, normalizing, and preserving protected spans |
| [`server/src/services/compression/pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/pipeline.ts) | Orchestrates compression; integrates preservation step |
| [`server/src/services/compression/config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/config.ts) | Defines default protected-span delimiters and settings |
| [`server/src/__tests__/services/compression.test.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/preservation.ts) module detects marked regions using configurable delimiters from [`config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/config.ts)
- Overlapping spans merge into disjoint intervals via `mergeSpans()` to simplify reintegration
- [`pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/compression/config.ts). The `findProtectedSpans()` function in [`preservation.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/pipeline.ts).

### Is the preservation behavior tested for repeated compression runs?

Yes. The test suite in [`compression.test.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.