v0.4.0b1 — pathway identity + packet mode

Pathway-layer reframe — Helix weighs, doesn't retrieve

0.4.0b1 is a meaningful identity shift. Helix is no longer framed as a
knowledge store that competes with vector DBs; it's a coordinate
index layer that emits confidence so agents can decide know-vs-go
without being coaxed into it. Composes on top of the bundled SQLite
genome today, stacks on any content store tomorrow.

Two product surfaces

• /context/packet — agent-safe index. Returns pointers +
  verified / stale_risk / needs_refresh verdict + refresh plan.
  Caller fetches content. Task-sensitive (plan / explain / review /
  edit / debug / ops / quote).
• /context — decoder path. Helix assembles + compresses the
  context window. Downstream LLM consumes directly. Unchanged
  behavior.

Weighing layer (the conceptual center of gravity)

coord_conf × (freshness × authority × specificity) = is-it-safe-to-act

• freshness_score — exp(-age / half_life[volatility_class]) with
  stable=7d / medium=12h / hot=15min half-lives
• authority_score — primary=1.0, derived=0.75, inferred=0.45
• specificity_score — literal=1.0, span=0.9, doc=0.75,
  assertion=0.45
• coord confidence — path_token_coverage between query signals
  and delivered gene source paths (hit mean 1.00 vs miss mean 0.52 on
  the 10-needle bench)

Validated via Phase 5 packet bench — 10/10 scenarios pass across 5
families (stale_by_age, coordinate_mismatch, task_sensitivity,
authority_downgrade, clean_verified). See
`benchmarks/bench_packet.py`.

Ingest-time provenance

New columns on `Gene` (auto-populated from file extension at
ingest): `source_kind`, `volatility_class`, `observed_at`,
`last_verified_at`. No backfill needed for new ingests. Existing
genomes can run the one-time `scripts/backfill_gene_provenance.py`
sweep.

New endpoints

• `POST /context/packet` — the agent-safe index surface
• `POST /context/refresh-plan` — just the reread plan
• `POST /fingerprint` — navigation-first retrieval with `score_floor`
  • honest accounting (`evaluated_total`, `above_floor_total`,
    `filtered_by_floor`, `truncated_by_cap`)

New MCP tools

• `helix_context_packet`
• `helix_refresh_targets`

Plus the full existing suite (`helix_context`, `helix_stats`,
`helix_ingest`, `helix_resonance`, session/HITL toolkit).

Dep additions

• `[mcp]` extra — required for `python -m helix_context.mcp_server`
  (closes an import-error gap)
• `[nli]` extra — standalone torch + transformers for DeBERTa/NLI
  backends
• `[all]` extra now genuinely complete

Docs v2

• README v2 — lead with pathway identity, two-surface layout,
  launch modes table, LLM-free pipeline as load-bearing framing
• docs/architecture/PIPELINE_LANES.md v2 — adds /context/packet,
  /context/refresh-plan, /fingerprint lanes; weighing layer as
  first-class concept
• New docs/specs/2026-04-17-agent-context-index-build-spec.md —
  657-line authoritative packet-mode spec

Migration notes

• Existing `/context` callers: no action needed. The new
  confidence fields appear on `ContextHealth` additively.
• MCP hosts: run `pip install helix-context[mcp]` if you use
  `python -m helix_context.mcp_server`.
• Existing genomes: optional one-time run of
  `python scripts/backfill_gene_provenance.py` to populate
  provenance fields on legacy rows (so packet mode returns
  `verified` instead of `stale_risk`).

Validation

• 680+ tests pass (one pre-existing test fixed in this release)
• Phase 5 packet bench: 10/10 across 5 families
• Dry-run install verified from clean resolution: `.[all]` pulls
  mcp, torch, transformers, sentence-transformers, spacy, tree-sitter,
  opentelemetry stack, headroom-ai[proxy,code].

Powered by Agentome.