Verification and module map

This doc is for maintainers. User-facing entrypoints live in README.md, docs/quickstarts.md, docs/tool-reference.md, and docs/examples.md.

Standard check

npm run check

This runs, in order:

1. npm test
2. npm run pack:dry

Individual gates

npm test
npm run pack:dry
node --test test/boundary-audit.test.js
node bin/emet.js doctor

npm run pack:dry runs the package surface audit before npm pack --dry-run, including bin modes, version sync, and dependency sanity.

Current layers

Layer	Files	Role
Facade	lib/web-research.js	thin re-export facade for backward compatibility
Workbench	lib/research/pipeline.js	main research orchestrator
Platform	lib/research/{queries,search,fetch,synthesis}.js	query building, search, fetch, synthesis
Adapter	lib/retrieval/community.js, lib/collectors/*	community/media retrieval and normalization entry
Base	lib/research-flow.js, lib/research-contract.js, lib/research-session.js, lib/retrieval/normalize.js	policy, contracts, bounded session state, normalized candidates
Infra	lib/research-memory.js, lib/local-logger.js, lib/tiny-router.js	storage, logging, optional local ML/router runtime

Dependency direction

Allowed:
  web-research.js        -> research/* re-exports only
  research/pipeline.js   -> research/*, retrieval/*, policy/base modules
  retrieval/*            -> collectors/*, normalized/base modules
  base/policy modules    -> pure helpers only
  adapters/hosts         -> public runtime/facade only

Forbidden:
  lib/web-research.js    -> new implementation logic
  base modules           -> platform/adapter imports
  collectors/*           -> synthesis or sufficiency logic
  MCP/Pi/CLI handlers    -> collector internals

Page-fetch adapter note

lib/page-fetch-adapter.js is the small Node-side heuristic layer for blocked/thin/dynamic pages. The function name chooseScraplingMode() is historical naming only; the repo does not require a local Scrapling/ checkout or .venv-scrapling/ anymore.

Verify its behavior with:

node --test test/page-fetch-adapter.test.js test/web-research.test.js

Boundary audit

node --test test/boundary-audit.test.js

This test verifies that core policy/evidence modules import no adapter internals, adapters import no individual collector implementations, domain packs import no I/O modules, and memory/logging/traces serialize no raw secrets.