docs: design third-party MIB catalogs

[larimonious]

Summary

Extend DD-047 with the implementation, compatibility, and security contract for updateable third-party MIB-driven device inventory.

The design separates three typed layers and compiles them into one immutable catalog:

1. MIB schemas (SMIv1/SMIv2 symbols, types, tables, indexes, and access metadata)
2. Device-recognition profiles (numeric sysObjectID rules plus bounded literal evidence)
3. Finite read-only inventory plans compiled to numeric OIDs

It also freezes the bounded GETNEXT WALK envelope and exact resource algebra before that API ships.

Key decisions

• Raw MIB/profile/plan source is compiled in a bounded isolated worker through ntnt netmon mib compile; polling and ordinary stdlib calls never parse source text.
• Source schemas are closed and explicitly list every path plus expected module/profile/plan identity.
• The .ntntc artifact has exact framing, RFC 8785 canonical JSON, per-symbol/record/aggregate hashes, and a full-artifact SHA-256.
• Runtime recomputes every semantic hash before publishing one immutable Arc<CatalogSnapshot>.
• Content-addressed publication is atomic no-replace. Compiler failure cannot select or replace application configuration; prior artifacts remain deployment-owned rollback candidates.
• Catalog paths are application-root confined, no-follow, regular-file and size bounded, and validated from the same opened handle.
• Missing catalog configuration leaves numeric GET/WALK usable. Invalid configured artifacts abort every application/worker startup path before traffic or job claims.
• Ordinary ntnt programs do not receive a mutable mib_load(path) API.
• Recognition is advisory and cannot grant network authority, select credentials, raise caps, execute code, or use SNMP SET.
• Low-level snmp_get/snmp_walk remain numeric; named resolution occurs explicitly against one snapshot.
• Production v1 uses immutable artifacts plus restart/rolling restart. Runtime performs no automatic downloads or live reload.
• Generic std/jobs semantics remain application-owned. PR 2's optional device_inventory.expected fence returns a no-network catalog_mismatch envelope for queued runs.

WALK contract frozen here

• GETNEXT first; GETBULK later.
• One cursor and exactly one correlated response varbind per logical request.
• One whole-operation deadline.
• Strict increasing OIDs, subtree enforcement, loop rejection, and explicit protocol-exception completion.
• Mandatory look-ahead at max_results to distinguish exact completion from truncation.
• Checked preflight equation: (max_results + 1) * (retries + 1) <= 4096.
• Independent dynamic ceilings for cumulative received bytes and conservative normalized output.
• Exact termination matrix: low-level protocol/transport/budget failures never become partial telemetry.

Inventory contract

• Recognition probes and every plan section share one aggregate deadline/request/attempt/row/byte/output budget.
• Exact profile, plan, section, and catalog provenance is returned.
• Static profile ties fail compilation; runtime evidence ambiguity returns an explicit non-inventory result.
• Optional unsupported sections may be partial; security, protocol, global-budget, and required-section failures fail closed.

Parser research

A throwaway mib-rs 0.8.0 spike verified SMIv1/SMIv2 imports, symbolic and instance OID resolution, and Send + Sync registry state. Independent ecosystem review found it is the strongest Rust parser/resolver base, but too young and insufficiently budgeted to expose directly to untrusted runtime input.

The design therefore requires an ntnt-controlled exact-source fork/vendor snapshot with implicit/system loaders removed, parser concurrency fixed to one by default, checked byte/token/node/import/depth/time/heap budgets, three-platform corpus tests, and an ntnt-owned canonical runtime reader independent of parser-native types.

Validation

• git diff --check
• Markdown fence-balance validation
• cargo run --locked -- docs --validate
• Greptile 5/5 with no unresolved threads on the initial head
• Two independent architecture/implementation reviews identified blocking contradictions
• Two exact-staged-diff re-reviews verified the fixes
• Final bounded adjudication: PASS at staged diff 4484a712a6058cd7a772cc31272fc907f76705318210277da3d1a3abe97aa3e2

Delivery sequence

1. Bounded numeric GETNEXT WALK
2. Canonical MIB/profile/plan compiler plus immutable runtime registry and pure lookup APIs
3. Device recognition and profile-selected inventory execution with expected-hash fencing
4. IF-MIB normalization and counters
5. Rate/reset/wrap semantics

[larimonious]

@greptileai review

[greptile-apps]

Greptile Summary

Implements bounded SNMP GETNEXT walking and expands the third-party MIB catalog design.

• Adds snmp_walk with strict target policy, global deadlines, retries, mandatory limit look-ahead, protocol validation, and byte/output ceilings.
• Extends the SNMP codec with GETNEXT encoding and stale request-ID handling.
• Adds type signatures, documentation, examples, release notes, and comprehensive WALK tests.
• Defines the future immutable MIB/profile/inventory-plan compilation and deployment contract.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/stdlib/netmon.rs	Adds the bounded SNMP WALK runtime, strict option parsing, transport handling, look-ahead semantics, and resource accounting.
src/stdlib/netmon_codec.rs	Adds canonical GETNEXT request encoding and correlated response decoding that can ignore stale request IDs.
tests/std_netmon_walk_tests.rs	Exercises successful walks, terminal conditions, limits, malformed responses, stale packets, retries, deadlines, and policy failures.
src/typechecker.rs	Registers the new snmp_walk signature while preserving the optional fourth argument for both SNMP functions.
design-docs/dd-047-std-netmon.md	Specifies immutable third-party MIB catalogs, recognition profiles, inventory plans, and the finalized WALK contract.
docs/STDLIB_REFERENCE.md	Publishes the generated reference entry for the new SNMP WALK API.
Cargo.toml	Advances the package version to 0.5.3 without changing dependencies.

Sequence Diagram

sequenceDiagram
    participant Program as ntnt program
    participant Walk as snmp_walk
    participant Policy as Target policy
    participant Agent as SNMP agent

    Program->>Walk: target, auth, root OID, options
    Walk->>Policy: validate literal address and authority
    Policy-->>Walk: allowed
    loop Until terminal response or limit look-ahead
        Walk->>Agent: GETNEXT(cursor)
        alt stale request ID
            Agent-->>Walk: stale response
            Walk->>Walk: charge bytes and ignore
        else ordinary value
            Agent-->>Walk: correlated varbind
            Walk->>Walk: validate increasing OID and budgets
        else terminal exception or outside subtree
            Agent-->>Walk: terminal response
            Walk-->>Program: complete result
        end
    end
    Walk-->>Program: bounded result or error

Loading

_{Reviews (4): Last reviewed commit: "Merge pull request #172 from ntntlang/fe..." | Re-trigger Greptile}

[larimonious]

@greptileai review