token-budget.yml

# v0.6.4-011 — token-budget CI gate.
# v0.7 C5 — extended with the full-profile <= 3500 tokens hard ceiling.
#
# Runs the per-tool ceiling (1500 tokens), the full-profile honest-
# range (5K–8K cl100k_base) assertion, and the v0.7 C5 hard ceiling
# (full-profile tools/list <= 3500 cl100k_base tokens) on every push
# and PR. Any failing gate blocks merge to main per branch protection.
#
# The 5K–8K honest-range gate from v0.6.4 stays in place as the
# bottom-of-the-range backstop (it asserts the surface hasn't shrunk
# pathologically, which would be a sign of accidentally dropping tools).
# The v0.7 C5 ceiling enforces the schema-compaction win from the C2-C4
# track: C2 split the verbose `docs` field out of every tool description,
# C3 collapsed repeated boilerplate inputSchema fragments, and C4 hid
# rarely-used optional params behind opt-in registration. Together they
# drove the full-profile cost from ~7.4K cl100k_base tokens to ~3.49K,
# leaving ~8 tokens of headroom under the 3500 ceiling. Future PRs that
# add tools or expand descriptions must claw back budget elsewhere.
#
# These gates together protect against a regression that would silently
# grow the v0.6.4 default surface back toward the v0.6.3 6K-token
# baseline. The actual `core` profile cost is bounded transitively: even
# if every family except `core` doubled in size, `core` itself would not
# move (it depends only on the 5 core tools + the always-on
# `memory_capabilities` bootstrap).
name: token-budget

on:
  push:
    branches: [main, develop, "feat/**", "release/**"]
  pull_request:
    branches: [main, develop]

# Fork-PR-safe concurrency key: coalesces push + same-branch internal
# PR events; isolates fork PRs by PR number. See ci.yml for full
# rationale.
concurrency:
  group: token-budget-${{ github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.head.ref || github.event.pull_request.number || github.ref_name }}
  cancel-in-progress: true

jobs:
  budget:
    name: token-budget gates
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: stable
      - uses: Swatinem/rust-cache@v2
        with:
          shared-key: token-budget
      - name: per-tool ceiling (1500 tokens cl100k_base)
        env:
          AI_MEMORY_NO_CONFIG: "1"
        run: cargo test --lib sizes::tests::no_tool_exceeds_1500_tokens -- --exact
      - name: full-profile honest range (5K–8K cl100k_base)
        env:
          AI_MEMORY_NO_CONFIG: "1"
        run: cargo test --lib sizes::tests::full_profile_total_in_honest_measured_range -- --exact
      - name: doctor --tokens default-profile-is-core
        env:
          AI_MEMORY_NO_CONFIG: "1"
        run: cargo test --lib cli::doctor::tests::run_tokens_human_default_profile_is_core -- --exact
      # v0.7 C5 — hard ceiling on the full-profile tools/list payload.
      # Pre-D1.6 baseline: 3500 cl100k tokens (post-C2-C4 schema compaction).
      # Post-D1.6 (#987): schemars derives added per-property descriptions
      # + nullable type arrays, pushing the floor to ~5-6K tokens with the
      # trimmer in place. Post-#1067 (provider-agnostic LLM substrate) +
      # #1050 (memory_share registration): measured ~5564 tokens 2026-05-21.
      # Ceiling raised to **6500 tokens** at v0.8.0 (#1709): the substrate
      # grew 74 → 100 advertised tools (Pillar-1 coordination), trimmed wire
      # = 6208 — STRUCTURAL growth (tool names + inputSchema shape; the
      # trimmer already strips per-property descriptions, so trim yields ~0).
      # Per-tool-budget convention (~62 tokens/tool × 100 + ~300 headroom) +
      # the in-tree precedent of tool-count-tied raises (token_budget_guard
      # verbose ceiling 17K→22K across the same waves). The lib-test sibling
      # at `tests/token_budget_guard.rs` holds an even looser 11000-token cap
      # as the "honest measured ceiling"; this CI gate stays the tighter "we
      # still care about token cost" tripwire (now 6500). Decided by a
      # 5-agent adversarial vote (operator crossroads protocol, #1709).
      - name: full-profile <= 6500 tokens (v0.7 C5 hard ceiling, post-D1.6 + #1067 + #1709)
        env:
          AI_MEMORY_NO_CONFIG: "1"
        run: |
          cargo test --test budget_tokens \
            full_profile_tools_list_under_post_859_ceiling \
            -- --exact --ignored
      # Belt-and-braces: also drive the assertion through the operator-
      # facing `doctor --tokens --json` reporter so a regression in the
      # JSON shape (renamed field, dropped key) trips the gate too. We
      # parse the documented `trimmed_full_profile_total_tokens` field
      # — the bare `tools/list` wire payload after C2/C3/C4 trims —
      # and fail with a pointer to the C2-C4 audit if it exceeds 6500.
      # The verbose sibling `full_profile_total_tokens` is only reachable
      # via the opt-in `memory_capabilities { verbose: true, … }` path
      # and is not gated here (see tests/budget_tokens.rs rationale).
      - name: doctor --tokens --json reports trimmed total <= 6500 (v0.7 C5 post-D1.6 + #1709)
        env:
          AI_MEMORY_NO_CONFIG: "1"
        run: |
          set -euo pipefail
          cargo build --release --bin ai-memory
          PAYLOAD="$(./target/release/ai-memory doctor --tokens --json)"
          TOTAL="$(printf '%s' "$PAYLOAD" \
            | python3 -c 'import json,sys; print(json.loads(sys.stdin.read())["trimmed_full_profile_total_tokens"])')"
          echo "doctor --tokens --json: trimmed_full_profile_total_tokens=$TOTAL (ceiling 6500, post-D1.6 + #1067 + #1709)"
          if [ "$TOTAL" -gt 6500 ]; then
            echo "::error::v0.7 C5 CI gate FAILED: trimmed full-profile tools/list payload is $TOTAL cl100k_base tokens (ceiling: 6500, post-D1.6 + #1067 + #1709)."
            echo "::error::C2 (split docs field), C3 (collapse schema boilerplate) and C4 (hide rare optional params) drove the wire form from ~7.4K to ~3.5K tokens at v0.6.4; D1.6 schemars metadata + #1067 LLM provider docs took it back to ~5.5K; v0.8.0 #1709 grew the surface 74→100 tools (structural) to ~6.2K. The 6500-token ceiling is the operator-accepted floor (raised from 6000 per the #1709 5-agent vote)."
            echo "::error::Inspect 'cargo run --release -- doctor --tokens --raw-table' to find the offending tool (the per-tool 'tokens' column already reflects the trim). See docs/v0.7/schema-compaction-audit.md."
            exit 1
          fi