fix(campaign): publish search estimate method with package proof - #925

✅ Auto-approved PR — 0721e11d

Blanket team auto-approval is intentional. This is not a code review.
No automated review runs on this PR. This approval rests on the rule above alone.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-10-04T02:32:49Z}

Summary

• This PR exports the existing searchEstimateMethod function from the campaign package public surface, adds a compile-time & runtime check into scripts/verify-package-exports.mjs, and updates docs/public-api.md to reflect the newly published symbol. The change is small and focused; it appears correct and safe.

Files changed

1. docs/public-api.md
2. scripts/verify-package-exports.mjs
3. src/campaign/index.ts

Detailed review (file:line findings)

1. src/campaign/index.ts

• Change: new re-export entry added
  • Added lines (approx): 112–114
    • export {
      ...
      searchCellSetDigest,
      searchEstimateMethod,
      searchPosterior,
      } from './estimate-node'
• Findings:
  • Correctness: The function searchEstimateMethod is implemented in src/campaign/estimate-node.ts (see estimate-node.ts:74–79) and previously was only available via the internal path. Re-exporting it here correctly exposes the runtime function from the public campaign subpath.
  • Types: index.ts already re-exports the SearchEstimateMethod type from the search-ledger types elsewhere; re-exporting the function is consistent with publicly exposing the runtime helper and its type.
  • Import hygiene: Many internal modules import searchEstimateMethod directly from '../../campaign/estimate-node' (see e.g. src/search/lenses/shared.ts:11). Re-exporting on the campaign public surface does not break those internal imports and is a reasonable convenience for external consumers. No circular import appears introduced by this re-export (estimate-node imports lower-level modules and not index.ts), so no dependency cycle is introduced.
  • Suggestion: consider whether other internal callers should switch to importing from the public surface for consistency; not necessary but could be a follow-up.

2. src/campaign/estimate-node.ts

• Context: Function implementation exists and is unchanged.
  • Relevant lines: 74–79:
    • export function searchEstimateMethod(pairs: number): SearchEstimateMethod {
      if (pairs < 2) return 'none'
      if (pairs < DESCRIPTIVE_FROM) return 'insufficient'
      if (pairs < BOOTSTRAP_GATE_MIN_N) return 'descriptive'
      return 'bootstrap'
      }
• Findings:
  • Correctness: The mapping of pairs -> method is straightforward and well-documented in comments above. Constants used (DESCRIPTIVE_FROM, BOOTSTRAP_GATE_MIN_N) are defined sensibly: DESCRIPTIVE_FROM computed via minimumPairsForPairedDeltaTest(CONFIDENCE) (which returns 6 for confidence 0.95) and BOOTSTRAP_GATE_MIN_N = 20. The test matrix added in the script matches these thresholds: 0/1 -> 'none', 2–5 -> 'insufficient', 6–19 -> 'descriptive', >=20 -> 'bootstrap'.
  • No change here; only being published.

3. scripts/verify-package-exports.mjs

• Change: added compile-time type equality check and runtime cases for searchEstimateMethod.
  • Added import (approx lines 722–727):
    • import {
      searchEstimateMethod,
      type SearchEstimateMethod,
      } from '@tangle-network/agent-eval/campaign'
  • Added type equality and runtime checks (approx 749–776):
    • const searchEstimateMethodMatches: Equal<ReturnType, SearchEstimateMethod> = true
    • const searchEstimateCases: [number, SearchEstimateMethod][] = [ ... ]
    • for (const [pairs, expected] of searchEstimateCases) { ... }
  • Also added the symbol to the grouping of "void [ ... ]" (approx new ordering includes searchEstimateMethodMatches).
• Findings:
  • Correctness: The test covers both a type-level assertion (Equal<...> = true) and a small runtime sanity check matching expected outputs for representative inputs (0,1,2,5,6,19,20,100). As noted above, these correspond to the thresholds in estimate-node.ts (none/insufficient/descriptive/bootstrap).
  • Testing approach: This is a good addition — the script verifies that the exported runtime behaves as its declared type and provides canonical behaviour. The sample inputs include boundary values (1/2, 5/6, 19/20) which is appropriate.
  • Suggestion: You might include explicit comments noting where DESCRIPTIVE_FROM and BOOTSTRAP_GATE_MIN_N come from, but not required.
  • Organization: The import path used in the script is '@tangle-network/agent-eval/campaign' which will pick up the newly exported symbol; this is exactly the intent.

4. docs/public-api.md

• Changes:
  • Updated counts: published value exports and distinct symbols increased by 1 each, and production increased by 1 (lines near top).
  • Under ./campaign symbol table: added | searchEstimateMethod | production | this package: src/search/lenses/edit-credit.ts:34 |
• Findings:
  • Correctness: This correctly documents that searchEstimateMethod is now part of the campaign public API and marks it production.
  • Suggestion: The evidence points to src/search/lenses/edit-credit.ts:34, which currently imports searchEstimateMethod from '../../campaign/estimate-node' (internal path). If the canonical public surface is now the campaign subpath, consider updating internal reference evidence to point to the public subpath (minor doc nit).

Security considerations

• No new remote network access, secret handling, or eval-like constructs were added.
• The runtime check in scripts/verify-package-exports.mjs runs deterministic, pure functions and throws on mismatch; this is safe.
• The exported function is purely computational and deterministic; exposing it publicly is low risk.

Performance / Efficiency

• No runtime performance change: only a re-export and a small script test were added.
• The verify script runs a tiny loop over 8 cases; negligible cost.

Compatibility / API considerations

• Publishing searchEstimateMethod expands the public surface. This is backwards-compatible (additive).
• If consumers had previously imported it via internal paths, they can switch to the public path; maintainers should decide whether to keep the internal path import usage or migrate internal callers for consistency.
• No change to types or semantics of the function; behaviour is the same.

Suggestions / minor improvements

• (Docs) When documenting the new symbol in docs/public-api.md, you might prefer the evidence to point to the new public path or to the implementation location for clarity.
• (Code hygiene) Consider consolidating internal imports to the public surface where appropriate to reduce direct internal-path coupling (optional).
• (Verify script) The test is good; consider adding an explicit message on thrown Error to make failure debugging easier (the script currently throws a generic Error('packed search estimate method for ' + pairs + ...), which is okay but could include the actual method result).

Summary / overall verdict

• The changes are correct, minimal, and safe. The PR does what it claims: publishes searchEstimateMethod on the campaign package public surface, updates the public API documentation, and adds a compile-time and runtime check to package-export verification. No functional regressions or security concerns are apparent. I recommend merging.