0.0.1-preview.5 • Published 3d agoCLI

@nettoolskit/det

Licence

MIT

Version

0.0.1-preview.5

Deps

Size

48.4 MB

Vulns

Weekly

Install scriptsThis package runs scripts during installation (preinstall/install/postinstall)

Summary Dependency Versions

NetToolsKit DET

Semantic execution runtime for governed AI.

DET — Decision, Execution & Traceability — is the NetToolsKit semantic execution runtime for governed AI. It orchestrates, optimizes, and governs AI task execution through meaning, memory, verification, and metacognitive control.

DET coordinates AI models, MEVRA, Meaning Memory, tools, retrieval, verification, evaluation, policy, and metacognitive awareness so AI tasks can run with semantic grounding, traceability, safety, and measurable performance. It is not an agent framework and it does not own provider execution, memory storage, machine control, or downstream product orchestration.

The canonical and default DET function is host-controlled invocation: hosts such as Codex, Claude Code, GitHub Copilot, the CLI, a CI script, or another orchestrator invoke DET for semantic planning, admission, verification, and traceability. Internal or provider-mediated LLM calls are auxiliary admitted steps for DET-owned needs inside the graph; they are not the product focus, a competing operating mode, or the main control surface.

MEVRA proposes operational meaning. Meaning Memory validates and persists meaning. Metacognition monitors objective, focus, uncertainty, conflict, and risk. Verification validates. Anti-Deception protects. The LLM verbalizes. DET arbitrates the execution graph.

Features

Semantic execution runtime for governed AI task planning and execution.
Decision, execution, verification, traceability, and policy arbitration contracts.
Meaning Memory integration boundaries for global, catalog, project-registry, and project-local memory layers.
Agent and Codegen consumption boundaries that avoid duplicating deterministic function implementations.
Operational det run --task dry-run entrypoint for governed route planning and traceability.
Host-neutral DET invocation model with LLM use limited to admitted auxiliary steps.
Harness-derived evidence, benchmark, and effectiveness contracts inside the DET workspace.
River-first validation model for Rust quality, package validation, and CI/CD governance.

Introduction
Features
Architecture
- Architecture
- Agentic Surfaces
Crates
Compatibility and Support
Operations
Planning
Governance and Security
Build and Tests
Contributing
Dependencies
References
License

Architecture

flowchart LR
    User[Operator or host application] --> DET[DET runtime\nDecision, Execution & Traceability]
    DET --> MEVRA[MEVRA\nMeaning proposal]
    DET --> Memory[nettoolskit-memory\nMeaning Memory]
    DET --> Agent[nettoolskit-agent\nDeterministic functions]
    DET --> Codegen[nettoolskit-codegen\nComplex deterministic code architecture functions]
    DET --> Analytics[nettoolskit-analytics\nEvaluation and effectiveness signals]
    DET --> Harness[DET harness contracts\nEvidence and benchmark reproducibility]
    DET --> Rust[nettoolskit-rust\nShared Rust foundation]
    Copilot[nettoolskit-copilot] --> DET
    Copilot --> Control[nettoolskit-control\nRemote machine control]

DET owns semantic arbitration, execution planning, traceability, governance, and verification boundaries. It consumes nettoolskit-agent and nettoolskit-codegen deterministic functions without duplicating their code. It integrates with nettoolskit-memory through Meaning Memory contracts and keeps storage, indexing, retrieval, and persistence in Memory. Shared Rust abstractions come from nettoolskit-rust when they are product neutral; for example, DET runtime reference validation uses nettoolskit-validation instead of duplicating relative-path safety logic.

nettoolskit-copilot is a product surface that can use DET and remote control services. DET does not depend on Copilot or Control.

Agentic Surfaces

DET uses agentic ecosystem components through explicit boundaries:

nettoolskit-agent owns canonical deterministic function catalogs, commands, instruction contracts, and runtime guidance.
nettoolskit-codegen owns complex deterministic architecture/code-generation functions that DET can select and orchestrate.
nettoolskit-memory owns Meaning Memory storage, retrieval, validation, persistence, and project-local memory.
nettoolskit-analytics owns analytics and evaluation signals that DET can use for measured effectiveness.
nettoolskit-copilot owns user-facing product orchestration and can call DET.
nettoolskit-control owns remote machine command execution and is not called directly by DET.

Detailed architecture is maintained in ARCHITECTURE.md and docs/architecture-overview.md.

Crates

The DET workspace is organized by owned crates under crates/*.

Crate	Purpose	README
`agentic-rag`	Agentic RAG planning and policy contracts.	README
`cli`	Public CLI and compatibility facade.	README
`core`	Core semantic execution and repository profile contracts.	README
`harness`	Harness-derived evidence and reproducibility contracts.	README
`integrations`	Agent, Memory, analytics, and ecosystem integration boundaries.	README
`language`	DET language parsing and runtime-language contracts.	README
`runtime`	Runtime admission, DET home, wrapper, benchmark, and registry contracts.	README

Compatibility and Support

DET is in MVP implementation and should be consumed through committed Rust contracts, documented CLI surfaces, and explicit JSON request/response shapes. Distribution targets npm/npx, Docker, GitHub Releases, and Winget; Cargo publication is not the preferred operator install path for this product stage.

Supported operator paths and release-readiness details live in docs/install.md, docs/release.md.

Operations

Operational details are intentionally kept out of the root README:

Basic usage: docs/getting-started/basic-usage.md
First real use: docs/getting-started/first-real-use.md
Operational task runtime: det run --task --json <run-task-request.json>
DET home and Meaning Memory layers: docs/det-home-memory.md
Local validation and CI/CD routing: docs/operations/local-validation.md
River CI policy: docs/operations/river-ci.md
Runtime wrapper: docs/runtime-wrapper.md
Benchmark evidence: docs/local-det-vs-baseline-benchmark.md
Guarded DET dogfood with Agent and Meaning Memory: docs/guarded-det-dogfood.md

Planning

Planning state is kept under planning/ and should remain tied to concrete workstreams, validation evidence, and PR closeout.

Useful entry points:

Governance and Security

DET keeps execution ownership explicit:

DET arbitrates and plans; it does not duplicate provider, Agent, Codegen, Memory, Control, Copilot, DevOps, Assurance, or Analytics implementation code.
Memory owns retrieval, validation, persistence, indexing, and storage.
Agent owns deterministic function catalogs and command contracts.
Codegen owns complex deterministic architecture/code-generation functions.
Control owns remote machine command execution and is not a DET dependency.
Provider calls, MCP invocation, shell execution, persistence, and runtime IO require explicit host-owned boundaries.

See docs/det-ecosystem-ownership-model.md and docs/operations/river-ci.md for the detailed governance model. Use docs/operations/gitriver-ci.md for Access bridge routing and GitRiver incident triage.

Build and Tests

Local validation should mirror the River Rust quality gate:

cargo fmt --all --check
cargo test --all-targets --locked
cargo clippy --all-targets --locked -- -D warnings
cargo doc --no-deps --locked
git diff --check

Package/security validation is separate from Rust quality. PR runs should keep package security bounded by auditing dependencies, building docs, listing Cargo package contents, and generating allowlisted tarballs without repeating full workspace package verification. Full Cargo package verification is reserved for explicit release or manual proof.

The source-owned River validation path is documented in docs/operations/local-validation.md and docs/operations/river-ci.md.

Contributing

Use a dedicated branch or worktree for each change-bearing workstream. Keep changes scoped to the active plan, update README/manifest/changelog only when the implemented behavior changes, and record validation evidence before opening or updating a pull request.

Every completed workstream should leave the local worktree clean, planning state updated, and validation results reproducible from committed source.

Dependencies

Runtime dependencies are intentionally small:

Dependency	Purpose
`serde`	Public contract serialization and deserialization.
`serde_json`	JSON registry, manifest, and test serialization support.

Development and validation depend on the Rust toolchain, Cargo, cargo audit, and Git.

References

License

This project is licensed under the MIT License. See the LICENSE file at the repository root for details.

Package publication

Current source and next public preview target: @nettoolskit/det@0.0.1-preview.5. After the controlled release lane publishes GitHub Release v0.0.1-preview.5, npm preview and latest must both resolve to that exact version. Keep release evidence pinned to exact versions, and use det or ntk-det after global installation. GitRiver stage river/package runs package dry-run validation on pull requests, and river/release owns mutating publication only from main or v* source refs.