bug: algorithmic embedding subsampling diverges from its cited CBM source, and the stride>1 branch is untested #184

The divergence

mcp_server/shared/algorithmic_embedding.py::embed_text (added in #181, closing #169) implements frequent-token subsampling, and cites CBM's CBM_SEM_MAX_OCCUR = 512 as its source:

# source: CBM_SEM_MAX_OCCUR = 512 (semantic.h:52) — frequent-token subsampling
# cap; above this a token's co-occurrence pass is stride-sampled to ~this count.
_MAX_OCCUR = 512
...
stride = max(1, n // _MAX_OCCUR)          # n = total tokens in the document
for i in range(0, n, stride):
    tok = tokens[i]
    acc += w * cache[tok]                 # first-order term
    ...                                   # co-occurrence window

The cited source does something different in both trigger and scope. In src/semantic/semantic.c:874-884, occ_start..occ_end is the range of occurrences of one token id in the reverse index, and the stride guards only that token's co-occurrence pass:

static void cooccur_sparse_one_target(cooccur_sparse_ctx_t *cc, int tid, cbm_sem_vec_t *target) {
    int occ_start = cc->rev->offsets[tid];
    int occ_end   = cc->rev->offsets[tid + SKIP_ONE];
    int occ_step  = SKIP_ONE;
    if (occ_end - occ_start > CBM_SEM_MAX_OCCUR) {
        occ_step = (occ_end - occ_start) / CBM_SEM_MAX_OCCUR;
    }

So a 1,200-token memory of entirely distinct tokens gets stride=2 and half its positions never contribute a first-order term — a document CBM would never subsample, because no token repeats even twice. The module docstring states the CBM semantics ("a token occurring more than _MAX_OCCUR times in one document"), so docstring and code also disagree with each other.

Measured impact: small

I compared the shipped embed_text against a stride-forced-to-1 variant (CBM-faithful) at dim=384:

CBM's own rationale holds — "the enriched vector's direction is preserved (it's normalized after)". This is not a retrieval emergency, and I am not claiming the committed LongMemEval numbers are invalid. It is a source-fidelity defect (§8: the code does not do what the cited source says) plus a coverage gap, not a correctness one. Worth fixing on those grounds, not on alarm.

The coverage gap is the sharper half

tests_py/shared/test_algorithmic_embedding.py has 7 tests — dimension contract, determinism, normalization, empty input, sparse-ternary shape, semantic ordering, camelCase bridging. None exercises stride > 1. Every input is far under 512 tokens, so the subsampling branch has never executed in the suite. Under §12 every mutant of that branch survives; under §13 G1 it is an unmapped path in new code, which §13.3 makes blocking rather than a follow-up.

Acceptance criteria

1. Decide and state which semantics are intended, at the use site (§8):
   • (a) match the cited source — trigger on per-token occurrence count, stride only the co-occurrence pass, leave first-order terms complete; or
   • (b) keep document-length striding as a deliberate cost bound for prose, in which case the CBM_SEM_MAX_OCCUR citation no longer supports it and must be replaced by a measurement of the cost/quality trade-off at realistic memory lengths.
     Either is defensible. Silently citing (a) while doing (b) is not.
2. Docstring and code agree, whichever is chosen.
3. Tests cover the branch: a document that triggers striding, asserting the documented property (bounded work, direction preserved within a stated tolerance), plus the boundary at exactly _MAX_OCCUR tokens.
4. A negative assertion (§13 G4) that a normal-length memory takes stride == 1 — the case that must not silently change.
5. Mutation run (§12) scoped to algorithmic_embedding.py; every survivor killed or documented-equivalent. The stride branch is the specific target.
6. If (a) is chosen, re-run the committed benchmarks/results/semantic-fallback-169/ sweep and update the manifest — a changed embedder invalidates the recorded numbers (§8).

Not in question

The rest of #181 is well built: the signal-selection docstring states what was included and what was excluded and why (IDF omitted rather than faked — exactly right for a stateless per-text seam), hashing is hashlib-based for cross-platform determinism rather than salted hash(), and every constant carries a semantic.h line citation. The 413 tests across tests_py/shared, tests_py/infrastructure/test_semantic_fallback_169.py, tests_py/core/test_bridge_finder.py and tests_py/invariants pass on main. This issue is one branch inside an otherwise carefully sourced module.