ctxfw v3.7.0 — Dynamic Configuration, Engine Modes & FinOps Roast Engine

Summary

ctxfw v3.7.0 introduces dynamic runtime configuration, zero-downtime engine mode switching (distance vs passthrough), and a TTY-isolated FinOps Roast Engine. Additionally, this release achieves complete architectural hermetization: all legacy root shims have been purged, establishing src/ctxfw/ as the single source of truth across all 141 regression tests.

---

What's New in v3.7.0

1. Dynamic Configuration Subsystem (~/.ctxfw/config.json)

Manage firewall defaults, pricing models, and engine behaviors without touching code or manually editing JSON:

• CLI Commands:
  • ctxfw config list (or ctxfw config show): Dump formatted active configuration.
  • ctxfw config get <key>: Inspect specific parameters (e.g., ctxfw config get engine.mode).
  • ctxfw config set <key> <value>: Atomically mutate settings (e.g., ctxfw config set finops.roast_level cynical).
• Resilience & Atomic Writes:
  • Validated by strict Pydantic v2 schemas (EngineConfigDTO, FinOpsConfigDTO).
  • Corrupt or missing config files automatically fall back to canonical defaults with stderr notices without crashing background agents.
  • Mutations are committed via temporary staging files (.tmp) and atomic os.replace to prevent file truncation during concurrent reads.

2. Instant Engine Mode Switching (ctxfw mode)

Switch AST firewall behavior on the fly:

• ctxfw mode distance: Standard topological pruning (D0 intact, D1 typed stubs, D2+ nominal interfaces).
• ctxfw mode passthrough: Bypasses AST stripping while preserving telemetry tracking and proxy routing. Guarantees byte-for-byte fidelity when debugging complex upstream agent flows.

3. FinOps Roast Engine with Strict TTY Isolation

• Real-time technical commentary on token expenditure and cost elusion during interactive audits (ctxfw audit, ctxfw benchmark).
• Inviolable Stream Isolation: Evaluates sys.stdout.isatty(). In non-interactive environments (pipes, subshells, CI/CD runners, and agentic stdio loops), roast text and ANSI escape codes are 100% suppressed, preserving clean stdout streams.

4. Sanitized Executive Sharing Reports (ctxfw report --share)

Export audit summaries ready for security reviews and team sharing:

• Aggregates evaluated tokens, tokens avoided, and estimated USD ROI over local SQLite WAL history.
• Zero-Egress IP Shield: Excludes raw source code, variable names, database secrets, and absolute file paths.

5. Architectural Hermetization

• Purged all legacy shims from the repository root (contracts.py, topological_resolver.py, proxy_gateway.py, etc.).
• Direct package-level imports across the test suite (from ctxfw.core import ..., from ctxfw.storage import ...).
• Official namespace, repository URLs, and contact points aligned to heuristicolab.

---

Quality Assurance & Attestation

• Axiomatic Determinism: ACI 1.0000 ([PASS] READY FOR FORGE).
• Negative Invariants: 5/5 negative constraints formally attested in specs/config_and_roast.spec.md (Manifest Hash: 2a63e65e200442944f6f0c4d804a965681f4c919a9d306c26484b7903308dca1).
• Test Suite: 141 / 141 Passing (100% Green) across Python 3.10 – 3.14.
• Zero-Egress Certification: Distribution artifacts verified clean of local specs, databases, or environment secrets.

---

Installation & Upgrade

# Upgrade via PyPI
pip install --upgrade ctxfw

# Verify runtime health and stdio stream isolation
ctxfw doctor

# Inspect default configuration
ctxfw config list

**Full Changelog**: https://github.com/heuristicolab/ctxfw/compare/v3.6.0...v3.7.0

v3.6.0: Zero-Config MCP Agent Integration

Summary

ctxfw v3.6.0 delivers automated, zero-friction Model Context Protocol (MCP) integration via the newly upgraded ctxfw init CLI command. It provides instantaneous, idempotent onboarding for primary autonomous coding agents (Claude Desktop and Cursor), guaranteeing zero regression, strict configuration preservation, and defense-grade fault tolerance.

---

What's New in v3.6.0

1. Zero-Friction Agent Integration (ctxfw init)

Executing ctxfw init with zero arguments now performs automated discovery and idempotent injection of the Context Firewall MCP entrypoint across primary coding environments:

• Claude Desktop (Cross-Platform Dynamic Resolution):
  • macOS (Darwin): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json (with fallback to ~AppData/Roaming/Claude/...)
  • Linux / POSIX: ~/.config/Claude/claude_desktop_config.json
• Cursor (Workspace Scope):
  • Injects directly into .cursor/mcp.json within the current project working directory.

2. Standardized MCP Payload

{
  "mcpServers": {
    "ctxfw": {
      "command": "ctxfw",
      "args": ["mcp"]
    }
  }
}

3. Industrial Reliability & Inviolable Configuration Preservation

• Non-Destructive Merging: Preserves all pre-existing third-party MCP servers, top-level settings, and custom configuration keys intact.
• Strict Idempotency: If ctxfw is already registered, the configuration file is left untouched byte-for-byte and emits [~] <Agent>: ctxfw is already configured.
• Atomic File Swaps: Writes new configurations to a PID-scoped staging temporary file (.tmp_{name}_{pid}) before executing an atomic os.replace, completely preventing file truncation during sudden termination or concurrent process access.
• UTF-8 Byte Order Mark (BOM) Tolerance: Transparently handles and preserves configuration files encoded with UTF-8 BOM (\xef\xbb\xbf) generated by PowerShell or Windows editors.
• Directory Collision Protection: Guarded against directory collisions without crashing, gracefully reporting actionable status diagnostics.
• Shielded Multi-Agent Sweep: Gracefully isolates corrupt or unparseable JSON in one agent's config without interrupting discovery for other environments.

---

Quality Assurance & Verification

• Axiomatic Determinism: ACI 1.0000 (VERIFIED / [PASS] READY FOR FORGE).
• Test Suite: 124 / 124 Tests Passing (100% Green) across Python 3.10 – 3.14.
  • 109 core baseline tests verified with zero regression.
  • 15 comprehensive tests covering cross-platform resolution, UTF-8 BOM, atomic writes, and CLI entrypoints.
• Code Standards: Strict typing, Pydantic v2 immutability, zero cloud egress.

---

Quick Start

# Upgrade to v3.6.0
pip install --upgrade ctxfw

# Zero-config integration for Claude Desktop & Cursor
ctxfw init

# Verify local perimeter health
ctxfw doctor

Distribution Artifacts & Hashes (SHA-256)

• Wheel: ctxfw-3.6.0-py3-none-any.whl
0a1f6494019e193ced62bbeb3c36f1bf45572a7203fa05da23fdb7cfdfd8bca5
• Source: ctxfw-3.6.0.tar.gz
8191499b36861297436cff3672bf1e8692dbc676f2f4cee57b37dfffc772a845

v3.5.7: Dynamic Telemetry Unification & PEP 621 Metadata

CTXFW v3.5.7 // High-Assurance Context Firewall & In-Memory AST Pruner

Official maintenance release aligning package telemetry, PyPI ecosystem bindings, and dynamic terminal diagnostics.

What's Changed

• PEP 621 Project URLs: Bound official repository, issue tracker, documentation, and changelog URLs directly into pyproject.toml metadata for automatic syndication across PyPI and downstream package registries.
• Dynamic ASCII Diagnostic Banner: Refactored installer.py and cli/main.py to resolve and render __version__ dynamically from ctxfw.__init__ across both ANSI Unicode and ASCII fallback terminals.
• Axiomatic Integrity Attestation: Formal verification passing with ACI: 1.0000 (7 active negative invariants, SPEC.axioms.md verified).
• Test Suite Health: 109 / 109 unit and integration tests passing cleanly (pytest).
• MCP Certification: Certified Grade A (4.4 / 5.0) on the official Glama MCP Directory across 3 atomic tools (prune_file, resolve_context_bundle, evaluate_spec_axioms).

Distribution Artifacts

• Wheel: ctxfw-3.5.7-py3-none-any.whl (SHA-256 verified)
• Source: ctxfw-3.5.7.tar.gz

Install directly from PyPI:

pip install ctxfw==3.5.7
ctxfw doctor

v3.5.6 - Clean Protocol Documentation & TDQS Assurance

Highlights in v3.5.6

• Standardized Distribution: Streamlined official installation exclusively via PyPI (pip install ctxfw) and native stdio MCP configuration. Purged legacy registry references.
• TDQS Protocol Compliance: Full compliance with Glama Tool Definition Quality Standards (TDQS), including typed output schemas and explicit protocol annotations (readOnlyHint: true, destructiveHint: false, idempotentHint: true).
• Deterministic AST Compactor: In-memory Tree-Sitter pruning (-72.4% token mass in <60ms) verified across polyglot test suite (108/108 passing tests).
• High-Assurance Intake Sieve: Formal specification gatekeeper with ACI >= 0.9000 enforcement and SHA-256 seal integrity.

Quick Install

pip install --upgrade ctxfw
ctxfw doctor

Direct MCP Configuration (claude_desktop_config.json / Cursor)
JSON
{
  "mcpServers": {
    "ctxfw": {
      "command": "ctxfw-mcp",
      "args": ["--root", "."]
    }
  }
}

v3.5.5 - Glama TDQS Quality Compliance & Typed Tool Schemas Description:

Changes in v3.5.5

• MCP Protocol: Strict adherence to Glama TDQS standard (purpose clarity, usage guidelines, behavioral transparency).
• Tool Annotations: Added readOnlyHint, destructiveHint, idempotentHint, and openWorldHint across all endpoints.
• Output Schemas: Formal typed JSON schemas for tool responses.
• Engine: Dynamic version handshake and 108/108 passing verification tests.

v3.5.4 - Enterprise FinOps Audit Engine & Glama MCP Verified

Release v3.5.4

• FinOps: Enterprise attribution footer for benchmark audits.
• MCP: Fully validated by Glama cloud proxy (MCP spec 2024-11-05).
• Core: 108/108 passing tests, compiled Tree-Sitter AST pruning.

v3.5.3 - AST Attention Profiler & FinOps Telemetry

Changes in v3.5.3

• CLI: Native -v / --version argument support.
• Benchmark: Native empirical profiler subcommand with FinOps cost projection matrix.
• Architecture: Modularized CLI dispatcher package.
• Quality Gate: 108/108 passing tests, formal axiomatic specification integrity (ACI 1.0000).

v3.5.1 — Core Stability & AST Savings Invariant Sentry

CTXFW v3.5.1 // Core Stability & AST Invariant Sentry

Deterministic patch release addressing boundary clamping for topological pruning metrics, Windows runtime execution resilience in pre-commit hooks, and public empirical FinOps benchmarks.

🛡️ Axiomatic & Engine Fixes

• AST Savings Clamping (pruner.py, polyglot.py): Clamped metric calculations to strict [0.0, 100.0]% bounds, preventing negative savings reporting on minimal symbol files with AST stubbing overhead.
• Hook Execution Resilience (installer.py): Sentry hook now invokes python -m ctxfw.cli directly, eliminating WinError 193 and shell runner discrepancies on Windows developer environments.
• Topological Invariant Enforcement: Preserves strict interface signatures (D1) and nominal types (D2+) with zero AST syntax breakage.

📊 Empirical Benchmark Validation

Empirical context reduction metrics verified against ctxfw/cli.py across 16 internal dependencies:

• Raw Context: 49,096 tokens
• Topological Sieve: 20,014 tokens
• Net Reduction: -59.5% (29,222 bloat tokens eliminated)
• Compaction Latency: ~1,407 ms (In-memory Tree-Sitter parsing)
• Attestation: SHA-256 manifest sealed (ACI 1.0000)

📦 Installation

pip install --upgrade ctxfw
ctxfw doctor

CTXFW v3.5.0 // Sovereign In-Memory AST Context Firewall

High-Assurance AST Context Pruning & MCP Gatekeeper

Deterministic boundary between probabilistic LLM hallucination and production infrastructure.

Technical Highlights

• Topological AST Compactor: In-memory interface and contract pruning for TypeScript, Go, Java, and Python via Tree-Sitter (72.4% token bloat reduction).
• Zero Telemetry Egress: Local SQLite WAL high-concurrency cache with < 0.8ms warm hit overhead and zero external phone-home telemetry.
• Axiomatic Sieve Engine: Gatekeeper validating negative invariants (N >= 5) and bounded domains with ACI 1.0000 attestation.
• Standard Model Context Protocol: First-class stdio MCP server for Claude Desktop, Cursor, and Cline.

Quickstart

pip install ctxfw
ctxfw doctor