Adapters, environments and executors

When to use these kindsCopy Anchor Link

• You want a repository to use a specific source-control or CI provider instance. Use an AdapterSelector.
• A change needs a database clone or a namespace that is created for it and destroyed on a timer. Use an EnvironmentProvider.
• You run an author harness and want the router to know its capabilities and models. The adapter ships an ExecutorManifest, and your org pins it. See agent harnesses.

AdapterSelectorCopy Anchor Link

An AdapterSelector says which provider implements which port for its scope. The public example binds source control and CI at repository scope and lists the knowledge connections the repository may read.

apiVersion: numinance.dev/v1
kind: AdapterSelector
metadata: {name: payments, scope: SCOPE_REPO}
spec:
  ports:
    scm: {provider: dev.numinance.official/github, instance: main}
    ciexecutor: {provider: dev.numinance.official/jenkins, instance: ci-prod}
    knowledge: [confluence-eng, jira-pay]

Each binding is replaced as a unit. A repository cannot pair its own provider with the org's instance, because that would mix one scope's trust with another's configuration.

The ports themselves (scm, ticketing, ciexecutor and the others) are defined in the protocol; see capability ports. Official provider code is described under official providers.

EnvironmentProviderCopy Anchor Link

An EnvironmentProvider describes how a disposable environment is created for a change. Provisioning is idempotent by change id and tags the environment with it.

apiVersion: numinance.dev/v1
kind: EnvironmentProvider
metadata: {name: postgres-clone, scope: SCOPE_REPO}
spec:
  provider: dev.numinance.official/aurora-clone
  kind: ENVIRONMENT_KIND_DATABASE_CLONE
  source: payments-primary
  ttl: 14400s
  seed: [synthetic-customers]
  budget: {max_concurrent: 2}
  tags: {team: payments}

Every environment is ephemeral: ttl is required, and the loader refuses a value that is not above zero. seed: [synthetic-customers] names a data set; point it at synthetic or masked data, not production records. The profile context, not the open loader, checks the change_id tag rule.

ExecutorManifestCopy Anchor Link

An ExecutorManifest declares an author executor: its adapter, its capabilities, the models it may run and a cost class. Profiles select it by metadata.name, the executor id. One adapter ships one manifest per data path, so the same harness reaching a different model endpoint is a different manifest.

apiVersion: numinance.dev/v1
kind: ExecutorManifest
metadata: {name: claude-cli-bedrock, scope: SCOPE_ORG}
spec:
  provider: dev.numinance.official/claude-cli
  capabilities: [EXECUTOR_CAPABILITY_FILESYSTEM_READ, EXECUTOR_CAPABILITY_FILESYSTEM_WRITE, EXECUTOR_CAPABILITY_SHELL, EXECUTOR_CAPABILITY_SUBAGENTS,
    EXECUTOR_CAPABILITY_MCP, EXECUTOR_CAPABILITY_STRUCTURED_PLAN, EXECUTOR_CAPABILITY_APPROVAL_CALLBACKS]
  models:
    - {id: eu.anthropic.claude-sonnet-v1:0, max_context: 200000}
  cost_class: EXECUTOR_COST_CLASS_MEDIUM

A manifest is a claim, not a controlCopy Anchor Link

The schema comments are explicit: every field is a claim of the adapter author. The sandbox, the egress proxy and the credential broker enforce the request whatever the manifest says. Listing EXECUTOR_CAPABILITY_SHELL does not give an executor a shell, and omitting EXECUTOR_CAPABILITY_NETWORK is a statement about the adapter, not a firewall. Capabilities help the router match a playbook step to an executor that can plausibly do it.

Residency is not declared hereCopy Anchor Link

The public ExecutorManifest has no residency field. The schema reserves that slot for a later minor version and states that a residency class is never declared: until then, the class derived from the live configuration must still meet every floor, and a manifest that cannot be checked against a floor fails it. Adding residency: to a manifest is a schema error (shown below).

Security implicationsCopy Anchor Link

• A provider id must resolve to a lockfile entry. A selector naming a provider that is not installed and approved is useless, not dangerous; the failure surfaces when the profile is resolved.
• Binding replacement is atomic per port, so a repository cannot splice its own instance onto an org-approved provider.
• An EnvironmentProvider is a cost and data-exposure surface. ttl and max_concurrent bound it, and tags plus the change id make orphaned environments findable. source and seed are names; credentials never appear in them.
• ExecutorManifest is org-scoped only. A repository cannot introduce its own executor by committing a manifest.
• Agents cannot widen their own grants by editing these files. Configuration under protected paths changes through your normal review, not through the author agent.

Real failuresCopy Anchor Link

$ numi validate --files bad/doc.yaml      # AdapterSelector instance: "main prod"
invalid  file "doc.yaml": kind: invalid: a value of numinance.kinds.v1.AdapterBinding.instance fails its check
(exit 3)

$ numi validate --files bad/doc.yaml      # EnvironmentProvider ttl: 0s
invalid  file "doc.yaml": kind: invalid: a value of numinance.kinds.v1.EnvironmentProviderSpec.ttl fails its check
(exit 3)

$ numi validate --files bad/doc.yaml      # EnvironmentProvider ttl: 4h
invalid  file "doc.yaml": kind: does not match the kind schema: a value is not in protobuf JSON form
(exit 3)

$ numi validate --files bad/doc.yaml      # ExecutorManifest scope: SCOPE_REPO
invalid  file "doc.yaml": kind: invalid: ExecutorManifest is org-scoped only
(exit 3)

$ numi validate --files bad/doc.yaml      # model id "eu anthropic"
invalid  file "doc.yaml": kind: invalid: a value of numinance.kinds.v1.ExecutorModel.id fails its check
(exit 3)

$ numi validate --files bad/doc.yaml      # ExecutorManifest with an added "residency:" field
invalid  file "doc.yaml": kind: does not match the kind schema: schema: value does not match (violations: 1): \"/spec/residency\": additionalProperties
(exit 3)

Durations use the proto JSON form: seconds with an s suffix, so 4h is 14400s.

Next stepsCopy Anchor Link