Network analysis maintainer guide

The addon separates schemas, runtime enforcement, source-distributed workflows, framework handoffs, and conformance evidence so each boundary can evolve without silently weakening another.

Source map

Surface	Canonical location
Runtime API	`src/network-analysis/` and `src/network-analysis/index.ts`
Public exports	`src/api/index.ts` and generated `dist/src/network-analysis/` declarations
Contracts	`schemas/network-analysis/*.schema.json`
Schema catalog	`schemas/catalog/domains/network-analysis.json`
Addon workflow	`agentic/code/addons/network-analysis/`
Framework handoffs	`agentic/code/frameworks/*/docs/` and templates
Synthetic corpus	`test/fixtures/network-analysis/`
Release conformance	`test/conformance/network-analysis-v1/`
Architecture and controls	`docs/architecture/network-analysis.md`, `docs/security/network-analysis-*`

The runtime exports probing, recipe compilation, bounded offline analysis, evidence serialization/citations, Termshark handoff, research induction, forensic mapping, and SDLC/Ops comparison helpers. Keep subprocess calls on absolute executable paths, argument arrays, `shell: false`, isolated config, and explicit bounds.

Recipe maintenance

Every recipe is a complete `network-analysis.analysis-recipe/v1` document. When adding or changing one:

1. use only fields present in a checked probe inventory; 2. state direct observations separately from heuristics and list false-positive conditions; 3. keep metadata-only limits and stable locator requirements explicit; 4. define optional-field behavior and fail closed for a missing required field or unsupported major; 5. add a deterministic synthetic fixture or excerpt only when it proves new behavior without importing sensitive traffic; 6. update the catalog, unit tests, conformance report, and operator docs.

Reserved Zeek and Suricata extension points do not authorize an adapter. Adapters must produce the existing evidence contract, preserve source/tool identity, and pass the same disclosure, retention, and conformance gates.

Schema and API compatibility

The v1 JSON Schemas are additive contracts. Optional properties and enum values may be added only after consumer tests show unknown-value handling. Removing or renaming a property, changing meaning, weakening a bound, or making an optional property required needs a new schema identity and migration guide.

Runtime exports follow the repository CalVer release. A proposed removal must:

• ship a documented replacement first;
• add an explicit deprecation notice and migration example;
• remain supported through at least two stable releases and 90 days;
• retain fixture and consumer coverage during the window;
• record the removal release in both this addon's changelog and root changelog.

Tool compatibility is feature-detected. Do not extend a version range from a version string alone. Qualify required formats, statistics, fields, synthetic read behavior, and resource limits on every declared maintained line. Update the dated compatibility matrix and fixture provenance together.

Fixture authoring

Run the deterministic generator and the dedicated conformance target:

node test/fixtures/network-analysis/generate-fixtures.mjs
npm run test:conformance:network-analysis

Review `manifest.v1.json` for source license, purpose, expected classification, size, and SHA-256. Confirm regeneration produces no diff. Fixtures must be synthetic, tiny, redistributable, and free of real identifiers, secrets, or payloads. Invalid-format fixtures should isolate one failure mode.

Installed-TShark qualification remains an explicit conditional test and must report a skip when the executable is absent. It must never start live capture.

Documentation and integration maintenance

Keep the addon README, operator guide, compatibility matrix, schema index, recipe catalog, integration index, public addon page, root addon catalog, and third-party notices aligned. Examples must be exercised by a test or generated from the deterministic fixture corpus. At every disclosure or viewer step, place privacy, retention, and cleanup guidance beside the action.

Framework ownership remains stable: research owns source quality and synthesis; the existing forensics network analyst owns investigative conclusions; security owns control findings; SDLC and Ops own verification and change decisions. The integration index maps these contracts.

Package and release gate

Before release, complete the release checklist. The integration suite round-trips representative project-scoped deployments and the provider conformance suite covers the user-scoped adapters named by the manifest. The package smoke test parses `npm pack --dry-run --json` and verifies the addon, runtime JavaScript, public declarations, schemas, compatibility docs, framework handoffs, notices, and conformance report are present while packet-tool binaries and raw captures are absent.