mix insider.candidates

Copy Markdown View Source

Operating contract for the Lab-only ExUnit candidate inventory. Every name, bound, and status below is copied from tools/insider_lab/lib/insider/discovery/ex_unit/inventory.ex and inventory_cli.ex at the current revision. A candidate is a static hint; it is never a confirmed defect, runtime cause, security impact, or financial impact.

Invocation

Run from tools/insider_lab. Compile first in a separate step: a cold Mix project writes compilation progress to stdout before the task starts, and the task's own output is exactly one JSON object followed by a newline.

mix compile
mix insider.candidates --root /path/to/project
mix insider.candidates --root /path/to/project --path test/integration
mix insider.candidates --root /path/to/project --path test/a_test.exs --path test/b_test.exs
SwitchTypeDefaultMaximumNotes
--rootstringcurrent working directoryMust be an existing directory (lstat, not followed).
--pathstring, repeatabletest32 selectors of 1 to 1,024 bytes eachFile or directory selectors relative to root. Exact paths only; no globs.
--max-filesinteger5,00020,000Eligible files are those ending in _test.exs.
--max-bytesinteger67,108,86467,108,864Total source bytes read.
--max-candidatesinteger5002,000Candidates kept after ranking.
--max-duration-msinteger10,00060,000Whole-scan deadline; the scan runs in a monitored process whose max_heap_size is 67,108,864 words, and a killed scan reports inventory_failed.

Repeating a scalar switch (--root, --max-*) is an argument error. Unknown switches and positional arguments are argument errors.

Exit status

ExitMeaningstdout
0clean: complete scan, no candidates (status clean, completeness complete)inventory JSON
2complete scan with candidates (status candidates, completeness complete)inventory JSON
3no eligible _test.exs file in the selection (status and completeness empty_selection)inventory JSON
4one or more files could not be analyzed (status and completeness unsupported_source)inventory JSON, including every candidate found
5a file, byte, or candidate bound was hit (status and completeness truncated)inventory JSON, including the candidates kept
64invalid arguments or optionsinsider.exunit-candidate-inventory-error/v1 with status invalid_input and reason invalid_arguments or invalid_options
70inventory could not be completedsame error schema with status failed, completeness infrastructure_failure, and a reason such as invalid_root, selector_not_found, selector_symlink, selector_unavailable, selector_outside_root, scan_timeout, or inventory_failed

Only 0 means "nothing found". Treat 3, 4, and 5 as incomplete evidence and 70 as an infrastructure failure; none of them is "no candidates". Exit 1 is never an inventory result: Mix uses it for an uncaught crash.

Completeness

Every inventory carries exactly one completeness state, chosen by this fixed precedence:

  1. truncated: truncation_reasons is non-empty.
  2. unsupported_source: unsupported is non-empty (a skipped symlink, an unreadable path, or invalid Elixir syntax).
  3. empty_selection: eligible_file_count is 0.
  4. complete: otherwise.

A lower-precedence condition that also holds stays visible in its own field; for example a truncated scan still lists its unsupported files. status is clean or candidates only when completeness is complete, and equals the completeness state otherwise.

Inventory document

Schema insider.exunit-candidate-inventory/v2. Version 2 adds completeness and changes status so clean no longer means only "no candidates"; the rest of the document is unchanged from v1. Top-level keys:

KeyContent
schemainsider.exunit-candidate-inventory/v2
scanner_revisionast-v8-telemetry-event-targets at this revision
classificationcandidate_inventory
statusclean, candidates, empty_selection, unsupported_source, or truncated
completenesscomplete, empty_selection, unsupported_source, or truncated
rootexpanded root path
pathsselectors as given
candidate_count, candidatesranked list, highest score first, ties by path
eligible_file_count_test.exs files found by the walk
scanned_file_count, scanned_bytesfiles and bytes actually read
unsupportedlist of {path, reason} with reason symlink_not_scanned, source_unavailable, or invalid_elixir_syntax
truncated, truncation_reasonsany of file_limit, byte_limit, candidate_limit
configuration_fingerprintSHA-256 over the effective options, scanner revision, and signal weights
source_fingerprintSHA-256 over the sorted {relative path, source fingerprint} pairs
limitationsstatic_signals_do_not_confirm_runtime_causality, only_explicit_reason_patterns_are_visible, only_elixir_test_sources_are_interpreted

Each candidate:

KeyContent
idSHA-256 over path, source fingerprint, reasons, targets, and truncation flag
classificationcandidate
pathrelative to root
source_fingerprintSHA-256 of the file bytes
scoresum of reason weights
reasonssorted by code; each has code, weight, lines, evidence
target_count, targets, targets_truncatedat most 64 deduplicated targets across all kinds

Signal codes and weights

CodeWeightEvidence text
application_env_absence_not_restored12cleanup converts a previously absent application environment entry into a value
application_env_mutation8mutates application environment without visible matching cleanup
global_telemetry_handler7attaches a VM-global telemetry handler without visible matching cleanup
otel_global_capture7changes or captures shared OpenTelemetry state
sleep_or_timer_wait4uses elapsed time for synchronization
explicit_test_serialization3declares async: false
application_env_cleanup_present2mutates application environment and declares matching cleanup
global_telemetry_cleanup_present1attaches a VM-global telemetry handler and declares matching cleanup

Cleanup credit is given only when the same application-env key or Telemetry handler id is released in the same lexical test, setup, setup_all, def, or defp scope. :telemetry_test.attach_event_handlers/2 never receives cleanup credit because its handler id is the returned reference.

Targets

Three kinds. All carry kind, operation, status, and oracle.

KindIdentity fieldsStatus values
application_envapplication, keyresolved (root-qualified Elixir.Application call), syntactic (with reason unqualified_module for an unqualified Application call or lexical_alias_without_macro_expansion for a visibly aliased key), unresolved
telemetry_handlerhandler (literal id passed to :telemetry.attach/4 or attach_many/4)resolved, unresolved
telemetry_eventevent (list of segment strings; one entry per literal event in :telemetry.attach/4, attach_many/4, or :telemetry_test.attach_event_handlers/2)resolved, unresolved

Unresolved targets carry reason dynamic_identity and oracle: null. Configured values, callbacks, and executable terms are never included.

The oracle hint

A static re-encoding of the identity already in the target, naming the fixed artifact and the exact environment inputs it validates. It installs, starts, and authorizes nothing.

  • application_env with status resolved or syntactic: {"schema": "insider.application-env-oracle/v1", "inputs": {"INSIDER_ORACLE_APPLICATION": app, "INSIDER_ORACLE_KEY": key}}.
  • telemetry_event with status resolved: {"schema": "insider.telemetry-dead-handlers-oracle/v1", "inputs": {"INSIDER_ORACLE_TELEMETRY_EVENT": "seg1,seg2,..."}}.
  • null for telemetry_handler, for unresolved targets, and whenever the artifact would reject or reinterpret the identity: a name or segment outside 1 to 255 bytes, more than 16 segments, an encoded event longer than 2,048 bytes, a segment containing a comma, or any byte below 0x20 (which could not pass through the environment unchanged).

The otel_global_capture signal has no target and therefore no hint; the OpenTelemetry artifact takes no selector.

A syntactic identity must be validated by you before use: a macro could shadow Application or alter the alias environment, and the scanner does not load or expand adopter code.

scanner_revision caveat

Candidate id values and configuration_fingerprint depend on the target extraction semantics of the scanner revision. Compare inventories only when scanner_revision matches; a new revision can change which targets a file yields and therefore its candidate identity even when source_fingerprint is unchanged.

What the scan does not do

It reads only exact selectors inside the declared root, rejects missing, escaping, or symlinked selectors, and does not follow symlinks during the walk. It parses Elixir with Code.string_to_quoted/2 and inspects executable AST only, so examples inside strings or quoted syntax are not behavior. It does not expand globs, load or evaluate target source, run tests, read credentials, contact providers, start a background scan or scheduler, invoke a model, or grant staging or production authority. Concurrent replacement of files during a scan is outside its trust boundary.