{"slug": "show-hn-a-deterministic-first-local-control-center-leveraging-ai-for-routing", "title": "Show HN: A Deterministic-First Local Control Center Leveraging AI for Routing", "summary": "Developer JuanVeranoMesa released Natta v1, a deterministic-first local control plane for registered repositories that uses AI only for optional semantic routing and bounded planning while deterministic code performs all execution. Natta's pipeline runs a request through strict validation, deterministic argument and project resolution, policy evaluation, authorization, handler/confinement validation, deterministic execution and post-execution verification, with the `route` command stopping at a proposed selection and `plan` limited to at most four linear intents in one provider call, neither executing. The toolkit requires macOS, Python 3.11+ and Git with no Python packages, virtual environment or model weights for the core, and its `codex` command hands off the terminal to a separately installed tool rather than implementing it.", "body_md": "A deterministic-first, AI-assisted toolkit for explicit local development/workflow capabilities.\n\nAI may select or plan from capabilities Natta explicitly knows about. Natta validates that decision. Deterministic code performs the actual work.\n\nNatta v1 is a small local control plane for registered repositories. Direct commands work without AI. Optional semantic routing and bounded planning add a convenience layer over the same handlers, policy and structured contracts.\n\n```\nrequest\n  → direct deterministic command OR bounded semantic decision\n  → strict validation\n  → deterministic argument/project resolution\n  → policy evaluation\n  → authorization where required\n  → handler/confinement validation\n  → deterministic execution\n  → post-execution verification\n  → structured result\n```\n\nThis describes the semantic execution boundary. Direct commands retain their\ncommand-specific validation and safeguards; they do not all pass through the\nsemantic gate. `route` stops at a proposed selection and `plan` stops at a\nvalidated plan. Neither executes. Capability types are atomic (one focused\noutcome), workflow (coordinated steps), and interface (a terminal/tool handoff).\nAdapters implement mechanics; routing selects; workflows compose structured data.\n\nNatta is not an autonomous agent system, arbitrary script runner, automatic plugin\ndiscovery framework, MCP-first framework, or coding-agent harness. The `codex`\ncommand hands off the terminal to a separately installed tool; Natta does not\nimplement that tool's behavior.\n\n| Command | Outcome | \n|---|---|\n| `projects` | List registered projects | \n| `status PROJECT` ,`context PROJECT` | Inspect identity, Git state, version and document paths | \n| `diff PROJECT` | Inspect staged/unstaged change summaries without external diff tools | \n| `doctor` | Required core health and separate optional readiness checks | \n| `build PROJECT` ,`test PROJECT` | Registered iOS/Xcode simulator workflows | \n| `verify PROJECT --level 1\\|2\\|3` | Explicit adapter-defined verification profile | \n| `commit PROJECT [--message TEXT]` | Stage all changes and make one local commit; never push | \n| `testflight PROJECT --check` | Local-only readiness inspection | \n| `testflight PROJECT [--confirm]` | Authorized signed archive/export and beta upload | \n| `codex [PROJECT]` | Interactive Codex handoff at checkout root or registered repository | \n| `route REQUEST` | One bounded semantic capability selection; no execution | \n| `execute [--confirm] REQUEST` | One validated semantic dispatch | \n| `plan GOAL` | At most four linear intents, one provider call; no execution | \n| `do [--confirm] GOAL` | Authorize a frozen plan, then sequential fail-fast dispatch | \n| `confinement validate` | Explicit local inspection-backend validation with disposable fixtures | \n\n`generic-git` supports inspection, local commit and Level 1 staged/unstaged\n`git diff --check`. It does not infer Python build or test commands. `ios-xcode`\nsupports configured simulator build/test and verification levels; TestFlight uses\nexisting signing/account setup. TestFlight does not submit App Review, publish an\napp, add testers, change versions or push Git state.\n\nCurrently supported/tested environment: **macOS**. Core requirements are Python\n3.11+ and Git. No Python packages, virtual environment or model weights are\nrequired for the core. See [dependency and compatibility details](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/docs/DEPENDENCIES.md).\n\nFrom the root of a local checkout:\n\n```\nexport PATH=\"$PWD/bin:$PATH\"\nnatta --help\nmkdir -p \"$HOME/.config/natta\"\ncp examples/projects.toml \"$HOME/.config/natta/projects.toml\"\n# Edit project paths and selections before running doctor.\nnatta doctor\n```\n\nPersist the checkout's absolute `bin` path in your shell's PATH configuration if\ndesired. Keep this wrapper in the checkout; copying it elsewhere changes its\nrelative source resolution. There is no installer, shell dependency, global\nPython installation, automatic dependency repair or dependency on another checkout.\n\nUser configuration defaults to `~/.config/natta/projects.toml`. The global\n`--registry PATH` option selects another file. No personal projects are shipped.\nThe [example registry](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/examples/projects.toml) is a template for fictitious\nrepositories, not a ready-made Xcode project or a promise that the paths exist.\n\n```\nschema_version = 1\n[[projects]]\nalias = \"example\"\naliases = [\"example-app\"]\nname = \"Example App\"\npath = \"~/Projects/example\"\ntype = \"generic-git\"\n```\n\nEach project must identify a Git repository root. Required fields are `alias`,\n`name`, `path`, and `type`; aliases are globally unique lowercase letters/digits,\nhyphens or underscores. `~` expands to your home directory. Relative project\npaths resolve against the registry file's directory, not the calling shell.\nOptional `agents`, `architecture`, `roadmap` and `version_source` paths must stay\ninside the registered project. Unknown fields/schema versions fail closed.\n\nFor Xcode, `[projects.execution]` selects a project **or** workspace, scheme,\nconfiguration and exact test targets/UI smoke identifiers. It accepts selections,\nnot executable shell text. See the [configuration walkthrough](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/examples/README.md)\nand [capability design](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/tools/natta/docs/TOOL_DESIGN.md).\n\n```\nnatta projects\nnatta status example\nnatta context example-app\nnatta diff example\nnatta verify example --level 1\nnatta --registry examples/projects.toml projects\nnatta route --json \"Verify Example App at level 1\"\nnatta plan --json \"Inspect Example App and then verify it at level 1\"\nnatta execute --confirm \"Verify Example App at level 1\"\n```\n\nSemantic commands use the existing Codex CLI provider boundary with explicit\n`gpt-6-luna`. Model access and CLI protocol compatibility are required; there is\nno provider fallback or retry. Requests and frozen bounded descriptions are\nsupplied to selection; planning also receives bounded project identity/aliases,\nnot arbitrary project files. Project/verify parameters are resolved locally.\nNatural-language wording never authorizes execution. Explicit policies require\ninvocation-local `--confirm` or affirmative terminal approval; JSON/non-TTY never\nprompt. `do` authorizes the entire frozen plan before any prefix and reuses the\nsingle-capability dispatcher. There is no autonomous replanning or rollback.\n\nDirect `projects` and `doctor` are available. Semantic `projects` and `doctor`\nintentionally remain unavailable because no validated confinement mode exists.\nSemantic `status`, `context`, and `diff` require successful **local** macOS\ninspection-confinement validation. No host receipt or inherited compatibility\nauthority is shipped. Read the [confinement contract](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/tools/natta/docs/MACOS_CONFINEMENT.md)\nbefore running `natta confinement validate`. Build/test/verify, commit and\nTestFlight use authorization and protected-state verification with the existing\nunconfined workflow limits.\n\n```\nnatta doctor --json\nnatta plan --json \"Inspect Example App\"\nnatta commit unknown-project --json\nnatta testflight sample --check --json\n```\n\nCommands that support `--json` use their own structured success/failure envelopes,\nincluding expected configuration and argument failures, with nonzero failure exit\ncodes. Inspection commands such as `status` use concise human output rather than\nclaiming universal JSON support. Programmer exceptions remain exceptions.\n`no_match` is a valid non-executing selection, not an infrastructure success\nsubstitute. [Result contracts](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/tools/natta/docs/RESULT_CONTRACT.md) define details.\n\n`doctor --json` exposes `core_ready`, required Check-shaped rows and optional\nprovider/runtime/confinement/TestFlight rows. Missing optional components do not\nfail core readiness. Doctor performs no model inference, build, signing or upload.\n\nWorkflow `--verbose` streams diagnostic output; `--log` explicitly retains logs\nunder `~/Library/Logs/NattaToolkit/`. Default temporary execution state is removed\non normal completion. Provider artifacts, local models and validation records use\n`~/Library/Application Support/NattaToolkit/`, separate from other installations.\nNo credentials belong in the registry. TestFlight credentials remain external.\n\nThe capability universe, strict provider protocol, handler/parameter/policy parity, project identity checks and authorization bound supported execution. Model output cannot become an arbitrary executable command through these routing contracts. Protected-state snapshots detect observable violations and fail closed; they do not roll back changes or prove the absence of network effects.\n\nThe provider process is **not independently sandboxed by Natta** from reading the\nhost. It may inherit host environment/process access according to its runtime.\nRestricted supplied context is not OS-enforced confidentiality. Not every\ndeterministic workflow is sandboxed; trusted Xcode build phases/tests and other\nthird-party code can have ordinary host filesystem/network effects. Arbitrary\nscripts are not inherently safe. See [the complete trust model](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/docs/SECURITY.md).\n\nOnly macOS is supported/tested for v1. Native semantic inspection uses legacy\n`sandbox-exec` and exact local validation; Xcode workflows and Apple services are\nmacOS-specific. Some stdlib/Git code is portable, but Linux/Windows are unvalidated\nand not advertised as supported.\n\nThe optional [isolated local-model research component](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/tools/natta-local-model/README.md)\nreturns bounded decisions as data and includes reproducible evaluation code.\nIt is experimental and does **not** replace the production semantic provider.\nEvaluated Qwen/OpenJEV selection quality was rejected for production routing.\nNo weights, downloaded caches, environments or external source projects are\nredistributed. Setup/download are explicit optional actions.\n\n```\ncd tools/natta\npython3 -B -m unittest discover -s tests -v\n```\n\nThe complete 447-test regression suite uses temporary repositories and mocked\nproviders/Apple commands. Historical-evidence-dependent tests now construct\nsynthetic comparison data; no safety test was removed. Sanitized evaluation inputs\nhave public control hashes and are not represented as newly measured benchmarks.\nSee [evaluation provenance](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/docs/EVALUATION.md).\n\nNew capabilities require deliberate integration: deterministic implementation,\nCLI registration, bounded metadata, parameter contracts, effect/policy declaration,\nhandler binding, protection/confinement where appropriate, result support and\nregression tests. Automatic arbitrary-script discovery is intentionally absent.\nThe [extension walkthrough](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/docs/EXTENDING.md) annotates the existing mechanism.\n\nThis v1 distribution derives from a verified personal implementation with 441 passing tests and no confirmed remaining core v1 bugs. It preserves that source architecture; packaging is not a new architecture or a public-host certification. Planning remains bounded/experimental; local-model research remains optional.\n\nThe [roadmap](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/docs/ROADMAP.md) separates present behavior from possible future\nwork. Broader platforms, new capabilities and stronger isolation would need\nseparate design and validation; none are promised or implemented by extraction.\n\nNatta Toolkit is released under the [MIT License](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/LICENSE).\n\nCopyright (c) 2026 Juan Desiderio Verano Mesa\n\nThird-party components retain their respective licenses. See\n[third-party provenance](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/docs/PROVENANCE.md) and\n[dependency documentation](https://github.com/JuanVeranoMesa/natta-toolkit/blob/main/docs/DEPENDENCIES.md) for additional details.", "url": "https://wpnews.pro/news/show-hn-a-deterministic-first-local-control-center-leveraging-ai-for-routing", "canonical_source": "https://github.com/JuanVeranoMesa/natta-toolkit", "published_at": "2026-10-06 11:28:33+00:00", "updated_at": "2026-10-06 11:49:33.297358+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "ai-infrastructure"], "entities": ["Natta", "JuanVeranoMesa", "Codex", "macOS", "Python 3.11", "Git", "TestFlight", "Xcode"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-a-deterministic-first-local-control-center-leveraging-ai-for-routing", "markdown": "https://wpnews.pro/news/show-hn-a-deterministic-first-local-control-center-leveraging-ai-for-routing.md", "text": "https://wpnews.pro/news/show-hn-a-deterministic-first-local-control-center-leveraging-ai-for-routing.txt", "jsonld": "https://wpnews.pro/news/show-hn-a-deterministic-first-local-control-center-leveraging-ai-for-routing.jsonld"}}