jackin❯ Context Engine — design spec

Research state: Incomplete

This folder is the product specification distilled from the token-optimization-techniques dossier and the current token-optimization tools hub. External-tool state was refreshed on 2026-08-12 against Caveman v2.0.0, Headroom v0.34.0, RTK v0.45.0, lean-ctx v3.9.18, sem v0.21.0, mq v0.8.2, fff v0.10.3, codedb v0.2.5838, and pxpipe v0.13.1. The current objective comparison, rising-tools scan, evidence ledger, and release register supersede dated tool snapshots. This specification still requires implementation-time source revalidation; a design donor is not a permanent dependency decision.

Research question

What context-engine architecture can reduce tokens and quota per accepted task without weakening quality, recovery, cache behavior, or capsule isolation?

Headline findings

Thesis

Every external token-optimization tool fights the same three battles: it must install itself into an agent environment it does not own, infer what the agent is doing from an incomplete interception boundary, and measure savings without owning provider billing or the counterfactual task path. jackin❯ owns the capsule, generates agent configuration, supervises the process, and parses per-session usage records. An embedded engine can therefore adopt reviewed mechanisms without global user-scope installers, overlapping hooks, a provider proxy, or self-reported gross counters.

Design targets

The dossier's measured invariants bound the design (all sourced in 01 — economics, 02 — baseline audit, current evaluation protocol):

• Dollar split (measured heavy session): cache reads 32% / cache writes 29% / thinking ~20% / visible output ~17% / uncached 2%. Token volume is 94% cache reads. 1 output token = 5 uncached input = 50 cache-read tokens.
• The defaults already bank ~4–5× (prompt caching −86.3% input-side, MCP schema deferral, Edit-diffs). The engine's job is the residual: protect the banked wins, then compress the write-time observation stream, then route.
• Honest ceiling: ≈2.5× defensible at zero quality loss; ≈5–6.2× if the model-routing flip passes the harness (Claude Sonnet 5 uses the new Opus-4.7+ tokenizer, so the compounding tokenizer discount in the downtier arithmetic applies only when pinning legacy Sonnet 4.6 / Haiku 4.5); no honest 10× — thinking (20% of dollars) is reachable only by effort/routing, and the cache-read floor of genuinely-used context is real.
• Workload split decides the lever: on this repo's docs-heavy transcripts, 76.2% of observation tokens came through native Read (RTK-blind) and only 16.5% through Bash. A code-heavy session inverts this. The engine must cover both interception points and measure its own split per capsule.
• For subscribers the metric flips to tasks-per-cap (cache reads ≈0.1× against the cap, T3): prefix stability and request volume outrank everything; style compression is demoted. The engine meters both objectives.

Six layers

        L5  MEMORY & STATE          one reversible store; handoff files; net-accounted injection
        L4  ROUTING & FLEET         effort tiers, model pinning, advisor, stagger/pre-warm,
                                    batch lane, quota/cap metering, auth-mode policy
        L3  OUTPUT & PROMPT         register pack, guard lines, report registers, codebook
        L2  OBSERVATION PIPELINE    write-time compression at the tool boundary:
                                    shims + filters + crushers + outlines + handles + CCR archive
        L1  RETRIEVAL               resident search (fff), entity/structure (sem-core, tree-sitter),
                                    markdown sections (mq), fused query verbs (codedb-shaped)
        L0  MEASUREMENT             usage ledger, cache-bust detector, thinking estimator,
                                    harness runner, canaries, CI token-budget linter

L0 is the foundation, not an afterthought: the 2026-08-12 refresh found no independent accepted-task A/B for any of the four current stable releases. Caveman v2.0.0 has a current first-party fixture benchmark; lean-ctx has a current observational report without an exact version; Headroom v0.34.0 and RTK v0.45.0 have current mechanism and vendor evidence only. The engine therefore ships measurement first and treats every compression feature as unproven until its own bounce-netted ledger, quality gates, and current-version task harness say otherwise.

Method and evidence

The design combines measured session invariants from the techniques dossier with a mechanism-level review of current tools. Each donor is classified as a dependency, port, reimplementation, or method reference; no vendor claim is treated as accepted-task evidence without the proposed harness.

Mechanism provenance

Structural advantages of capsule integration

1. No host writes, no installers, no drift. The engine's hooks, shims, MCP registration, and instruction files are composed at capsule build/launch inside /jackin/ — the entire installer/self-healing subsystem class disappears, and the host-write ban is satisfied by construction.
2. Enforcement instead of discipline. The adoption roadmap's "automatic beats disciplined" split becomes total: effort tiers, subagent model pins, report registers, and session-boundary routing are generated into agent config per role, not remembered by operators.
3. Whole-boundary visibility. The capsule supervisor sees every tool result (native reads via MCP tools it registers, shell via shims, web via its own fetchers), so the attention ledger, bounce netting, and reach measurement cover 100% of observation traffic — the number RTK/headroom/lean-ctx each only estimate for their slice.
4. Fleet-level economics. Staggered spawn, pre-warm, excludeDynamicSections, workspace-pinned cache lanes, batch-lane scheduling, and per-capsule cap attribution are orchestrator features — none of the seven tools has an orchestrator.
5. Honest self-measurement built in. crates/jackin-usage already parses per-agent session JSONL into token-class totals; the engine extends this into the harness the research defined but no tool ships.

Limitations and open questions

No reviewed tool has an independent, current-release accepted-task A/B that proves its headline savings. The proposed engine is therefore still a design: implementation must revalidate dependency versions, licenses, interception reach, cache effects, recovery behavior, and quality on representative jackin❯ tasks.

How to read

Related work

• Token-optimization techniques supplies the cost model, mechanism inventory, and validation requirements.
• Current token-optimization tools supplies the release register, tool comparisons, and evidence ledger.
• Context research places this specification in the broader research area.