Architecture
Intelligence and trust
are separate layers.
The engine reasons. Policy grants authority. The evidence can be verified independently. This page walks through each layer and the boundary that separates it from the next.
Status. This describes the designed model. Numinance is pre-alpha. Nothing here claims a shipped product, a customer deployment or a certification.
The model, end to end
Seven layers, one direction of authority.
Interactive architecture preview
- Proprietary
- Apache-2.0 · numinance-spec
- Customer-controlled environment
- Connected path
Diagram summary. Work flows top to bottom through seven layers. An engineering ticket reaches the private Numinance Engine, which proposes privileged capabilities. An external policy decision, outside the model, turns a proposal into a scoped grant or a denial. An authorized invocation crosses the open protocol and host boundary, defined in numinance-spec under Apache-2.0. Work runs in a customer-controlled execution environment and produces evidence, artifacts and receipts. An independent offline verifier, the public evidence/v1 verifier, checks that evidence. This is a conceptual explainer, not a claim that every layer is a literal synchronous runtime hop.
Policy decision + scoped grant
Evaluates a proposed privileged capability outside the language model. A permitted request receives a scoped grant, bounded by explicit authority, risk, environment and expiration.
A proposed action is not an authorization.
- What’s private
- The engine’s own reasoning for wanting the action. Policy does not take the model’s word for it.
- What’s open
- The governance vocabulary: capabilities, risk classes, execution modes and scoped authority are defined in the public spec.
Engineering intent / ticket
Work begins as an objective: a ticket, a request or a described change. Nothing here grants authority.
objective
proposed privileged capability
03Outside the modelPolicy decision + scoped grant
Evaluates a proposed privileged capability outside the language model. A permitted request receives a scoped grant, bounded by explicit authority, risk, environment and expiration.
A proposed action is not an authorization.
- What’s private
- The engine’s own reasoning for wanting the action. Policy does not take the model’s word for it.
- What’s open
- The governance vocabulary: capabilities, risk classes, execution modes and scoped authority are defined in the public spec.
authorized invocation
typed call
produces
exported
Apache-2.0 · numinance-specIndependent offline verification
The public evidence/v1 verifier can run offline, apart from the engine. It checks exported evidence against trust material the caller pins.
Conceptual explainer — not a claim that every box is a literal synchronous runtime hop.
Private intelligence. Open contract.
Numinance is two things with a deliberate line between them. The engine is proprietary. The contract around it is public and meant to be inspected and implemented independently.
Numinance Engine
Proprietary- The autonomous engineering intelligence and orchestration runtime.
- Reasoning about codebases and constraints, and routing work to appropriate executors.
- Not published in numinance-spec. Internal algorithms and infrastructure are not described on this site.
numinance-spec
Apache-2.0- Protobuf definitions, typed ports and governance annotations.
- Configuration kinds and JSON Schemas.
- The evidence/v1 chain and export verification specification, plus the numi CLI for public capabilities.
- Conformance suites, sample plugins, integration adapters and SDKs, as present in the public tree.
A fixed engineering loop.
The engine does not improvise its process. Every objective moves through the same five states, which turns open-ended work into a sequence of inspectable decisions.
- 01UnderstandDiscover context, contracts and constraints.
- 02PlanChoose a bounded approach and the checks expected to pass.
- 03ActInvoke explicitly authorized capabilities.
- 04VerifyEvaluate results against independent checks.
- 05EvidencePreserve records for outside verification.
The loop is a design. Individual stages are under development.
Bounded grants.
The model proposes. A proposed action is not an authorization. Before a privileged action, policy is evaluated outside the language model, and a permitted request receives a grant with explicit limits.
- Authority
- Which capability, on which resource, for which principal.
- Risk
- How consequential the action is, as classified by the governance vocabulary.
- Environment
- Where the action may run.
- Expiration
- Grants are time-limited. An expired grant authorizes nothing.
Decision inspector
Action
OpenPullRequest
Principal
Author agent
Resource
Fictional repository, feature branch
Grant
Present, scoped, unexpired
- 01
Requested
Pending
- 02
Risk classified
Pending
- 03
Policy evaluated
Pending
- 04
PermittedDenied
Pending
Fictional action and principals. The decision is made outside the model. This is a state sequence, not a recording of a real run.
Governance vocabulary
Seven typed concepts describe who is asking, how risky it is, and how it may run. Rows marked consulted are used in the scenario above.
| Type | Plain-English meaning | Illustrative value | In this decision |
|---|---|---|---|
| PrincipalKind | What kind of actor is asking. | An autonomous author, a human approver or a release pipeline. | consulted |
| RiskClass | How consequential an action is. | A read-only lookup versus a change other people will see. | consulted |
| ExecMode | How an action is allowed to run. | Run for real inside a sandbox, or only describe what would happen. | consulted |
| ResidencyClass | Where data and execution are allowed to live. | Stays inside the customer’s own cloud account. | not used |
| TrustClass | How much trust a component or result is given. | A reviewed first-party component versus an unreviewed third-party one. | not used |
| AutonomyLevel | How much the system may do without a person. | Only propose, or act within a bounded grant. | consulted |
| ChangeState | Where a change sits in its lifecycle. | Drafted, under review or released. | not used |
PrincipalKind
consultedWhat kind of actor is asking.
Illustrative: An autonomous author, a human approver or a release pipeline.
RiskClass
consultedHow consequential an action is.
Illustrative: A read-only lookup versus a change other people will see.
ExecMode
consultedHow an action is allowed to run.
Illustrative: Run for real inside a sandbox, or only describe what would happen.
ResidencyClass
not usedWhere data and execution are allowed to live.
Illustrative: Stays inside the customer’s own cloud account.
TrustClass
not usedHow much trust a component or result is given.
Illustrative: A reviewed first-party component versus an unreviewed third-party one.
AutonomyLevel
consultedHow much the system may do without a person.
Illustrative: Only propose, or act within a bounded grant.
ChangeState
not usedWhere a change sits in its lifecycle.
Illustrative: Drafted, under review or released.
The illustrative column is descriptive text, not a list of enum members. The real members of these types are defined in numinance.annotations.v1 / numinance.types.v1.
Separation of duties
01
Author
Proposes and implements the change.
02
Independent reviewer
Reviews the change. Not the author.
03
Release pipeline
Holds deployment authority under the design.
04
Human approver
Approves where policy requires a person.
Identity separation.
Authorship, review, release and approval belong to different identities. The author of a change cannot approve it. Under the design, deployment authority belongs to the release identity, not to the agent that wrote the code.
The strip in the decision inspector above shows the four roles. Roles are enforced by policy, not by asking the model to behave.
The customer-cloud model.
The technical design separates a customer-controlled data plane from vendor control-plane services. This is the designed deployment model. It does not imply a generally available on-premises installer or that every topology has shipped.
Designed to stay in the customer account
Source code, credentials, inference and infrastructure actions. The data plane runs in the customer’s cloud account.
What the vendor control plane sees
Limited coordination metadata. Metadata is not code and it is not credentials. The design bounds what crosses the line. It does not claim that no data of any kind ever crosses it.
Credential custody
A credential broker and controlled egress stand between sandboxed work and secrets. Work receives short-lived opaque handles, not reusable secrets.
Plugins and the host boundary.
Extensions run behind a typed boundary. A plugin implements one side of a published contract. The host mediates the other. Sandboxed work reaches nothing the host has not been asked, and allowed, to provide.
- numinance.plugin.v1
- The plugin protocol package.
- PluginService
- The service a plugin implements.
- HostService
- The service the host exposes to plugins.
- ActionContext
- The context an invocation carries.
- ActionResult
- The typed outcome of an invocation.
- Diagnostic
- A structured report of a problem.
- Envelope
- The common wrapper for configuration kinds, in numinance.kinds.v1.
- Digest · Reference
- Content addressing and typed links between records.
Descriptions are conceptual. Exact fields and members are defined in numinance-spec.
Evidence, checked outside.
Execution produces evidence, artifacts and receipts. Exported evidence is meant to be inspected independently of the engine. The public verifier can run offline.
$ numi evidence verify --runner-key FILE --log-key FILE --log-origin ORIGIN DIR
The verifier does not silently trust keys supplied by the export. A fully verified result requires the caller to pin the runner key(s), the log key and the origin, as the evidence specification defines. There is no built-in trust root.