Capability ports

When to use this pageCopy Anchor Link

Use it to choose which port a plugin implements, to look up exact RPC and message names, or to see what the host will do with a verb (its risk, whether it supports a dry run, what evidence it must produce). Plugin authors should also read Manifest and capabilities and the conformance guide.

How ports workCopy Anchor Link

• A port is a package numinance.ports.PORT.vN with one service. Each RPC carries the action annotation: risk, execution mode, idempotency, dry-run support, compensating action, declared evidence, capability and scopes.
• A plugin implements a port by serving its verbs behind PluginService.Invoke. The target of an Invoke is a port method, and the target's annotations in the host's descriptor copy govern it.
• Core verbs are never negotiated. A verb with a non-empty capability is negotiated at handshake and served only if both sides agree.
• The host refuses a provider that does not declare every side-effecting RPC of its port. For that reason the SCM and ticketing ports have no vendor escape hatch (no VendorCall): an escape hatch no provider implements would be a PRIVILEGED capability that does nothing.
• Ports are never model tools. Callers are named contexts of the runtime (release, execution, verification, evidence, knowledge), not the model.
• Payloads carry references and digests, not content, except where a port says a bounded value travels inline.
• Whatever a provider answers is untrusted data. It is size-limited, validated, stored by digest and labelled as untrusted wherever it reaches a prompt, ticket or pull request. No provider answer changes policy, a grant, a tool list or an approval.
• A provider holds no credential of its own. It asks the host for a credential handle for the intent its manifest declares.

The nine portsCopy Anchor Link

Reading the tablesCopy Anchor Link

Each row is one RPC. Risk is the RISK_CLASS_* value without its prefix and Exec the EXEC_MODE_* value without its prefix. A dash means the option is not set. All RPCs of a port are since: "1.0.0" unless the section says otherwise. Mapping from request and response messages to fields is in the proto file named at the top of each section; message names below are exact.

Status codes in the port comments (INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, RESOURCE_EXHAUSTED, UNAVAILABLE and so on) describe how providers report failure. A provider never invents a result: an outage is an error, never an empty answer.

scmCopy Anchor Link

proto/numinance/ports/scm/v1/scm.proto. Reads a source repository and its pull requests, and opens, updates, comments on and merges pull requests. Any code host with repositories, branches, pull requests, status checks and branch protection can implement every core verb.

• Callers: the release context calls the write verbs; the profile and policy side read the base revision through GetRepository; the knowledge side may read files and trees. OpenPullRequest, UpdatePullRequest, CommentOnPullRequest and CreateBranch run under the author-agent identity of the Change; MergePullRequest under the release-pipeline identity only. A merge by the author of the Change is refused by the policy floors before Invoke; the provider never decides who may merge.
• Every request names its repository in repository, marked resource_name: a repository outside the grant's resource scope is denied before dispatch.
• A revision is a full commit id (40 or 64 lowercase hex characters); a branch name or tag never stands for a revision, because it moves.
• OpenPullRequest declares evidence pr-ref; a call that succeeds without it is PARTIAL.
• GetBranchProtection reports what the host enforces. No verb of this port edits protection, a workflow file or a ruleset.
• No verb returns a diff.

Conformance kit: conformance/scm/v1.

ticketingCopy Anchor Link

proto/numinance/ports/ticketing/v1/ticketing.proto. Reads and searches issues, comments on an issue, moves it to a state category and links one issue to another as blocking it. Any tracker with projects, issues with a key, a title, a text body, a workflow of states, comments and issue links can implement every core verb.

• Every element is since: "1.2.0", newer than the other ports. The proto comments call 1.2.0 the first unreleased spec minor at the verified revision.
• Each request names its project in project, marked resource_name. LinkIssue names two projects and marks both.
• The change context calls GetIssue at intake. The write verbs are reached only under a policy decision, a redaction and a size cap.
• Write verbs (CommentOnIssue, TransitionIssue, LinkIssue) declare evidence ticketing-action; a call that succeeds without it is PARTIAL. LinkIssue has no compensating action because the port has no verb that removes a link.
• A provider answers NOT_FOUND with the same status and message for an issue that does not exist, one the credential may not see, and one whose current project differs from the request, so the port is not an oracle for issue existence.
• Tracker query languages are the capability ticketing.query_language, never a core field.

Conformance kit: conformance/ticketing/v1.

ciexecutorCopy Anchor Link

proto/numinance/ports/ciexecutor/v1/ciexecutor.proto. Starts, observes and cancels one run of a customer-owned pipeline (a CI job, a build or a release workflow) and reads its artifacts and log. A run is an OPERATION: StartOperation starts it and returns at once, GetOperation is the get, CancelOperation the cancel.

• Callers: only the release context, under the release-pipeline identity, for a Change at Releasing. The author of a Change is refused whatever identity kind it presents.
• The pipeline is customer-owned and never defined by the Change. The port has no verb that creates or edits a pipeline; a change to a pipeline definition is a change to a protected path.
• StartOperation is HIGH: it runs customer code with the customer's credentials in the customer's CI. It declares evidence ci-run-ref and the compensating action CiExecutorService.CancelOperation.
• A run's success is a fact about the pipeline, never an instruction and never an approval.

Conformance kit: conformance/ciexecutor/v1.

authorexecutorCopy Anchor Link

proto/numinance/ports/authorexecutor/v1/authorexecutor.proto. One coding harness behind one adapter, driven for one run of one work unit inside the work-unit sandbox.

• Callers: only the execution context, for a run whose actor kind is author-agent or reviewer-agent. A reviewer-agent run is read-only; its request has no allowed paths, no credential capabilities and no filesystem-write, shell or network capability, or the host refuses it.
• Of the request's references the provider may resolve only task_ref, plan_ref, context_bundle_ref and test_requirements_ref. worktree_ref and network_policy_ref are host_only.
• Execute is server-streaming: a stream holds 1 to 1023 events, the first is EXECUTION_STARTED at sequence 1, and only the last is EXECUTION_COMPLETED or EXECUTION_FAILED. Each ExecuteResponse is at most 32 KiB. Each event rides one RUNNING Invoke message (server-streaming targets).
• The stream is a provider claim; nothing in a request is advisory and nothing a provider reports is authority. Execute declares no evidence types: the execution context writes host receipts itself.

Conformance kit: conformance/authorexecutor/v1.

sandboxproviderCopy Anchor Link

proto/numinance/ports/sandboxprovider/v1/sandboxprovider.proto. Creates, runs, snapshots and destroys the one sandbox of one run of one work unit on the runner's host. One sandbox per run: a later run of the same work unit gets a new sandbox restored from a snapshot.

• Callers: only the sandbox context in the runner, under the runner identity. A provider bound to the runtime deployment serves it; the host refuses one installed from the registry.
• The host builds every sandbox spec from the run's grant, the policy decision and the plan. Nothing a provider reports is authority.
• The image is the one the runner holds under its digest and is never pulled. Run processes get an unprivileged OS user and can read no runner, broker, egress proxy or host credential state.
• Exec output is written outside the sandbox, is untrusted data, and is scanned by the host for issued handles.
• No RPC declares evidence yet; the host records the requested profile, image digest and limits, the provider's claims and its own checks.
• Create has Destroy as its compensating action.

Conformance kit: conformance/sandboxprovider/v1.

verifierCopy Anchor Link

proto/numinance/ports/verifier/v1/verifier.proto. One verifier runs its checks on one candidate and reports findings.

• Callers: only the verification context, for a run whose actor kind is reviewer-agent and whose actor principal and run id each differ from those of every author run of the Change. The host refuses a call that breaks either inequality.
• Run executes candidate code, so the verifier runs in its own sandbox with default-deny egress and no credential. The host refuses to dispatch Run to a verifier whose manifest or grant names any egress destination or credential intent.
• config_ref is the only configuration the checks honour; a candidate cannot switch a check off with a settings file or inline suppression.
• Findings are results, not failures: a run that finds violations SUCCEEDS. A check that crashes, times out or cannot complete ends the call FAILED with no findings, and the layer is inconclusive, never passed.
• Run declares evidence VerifierReport, a compact receipt of what the tool said, not the findings. The gate reads the verdict, never raw findings.

Conformance kit: conformance/verifier/v1.

knowledgeCopy Anchor Link

proto/numinance/ports/knowledge/v1/knowledge.proto. Read-only search and fetch against one approved KnowledgeConnection. Every verb is READ; the host and the broker refuse any non-READ capability on a knowledge connection, and there is no vendor call, since any escape hatch would be a write path.

• Callers: only the knowledge context (the Context Resolver).
• The provider reads with the credential handle the broker issued for the connection's auth, so the source enforces the principal's access at fetch. The port has no access-check verb.
• The provider runs sandboxed with default-deny egress; its only destinations are the hosts of its connection that the manifest names.
• In 1.0.0 query is search text only; vendor query languages are a later capability.
• Every title, snippet, ref, version and content is untrusted data; retrieved text never alters policy, tool lists, grants or approvals. No verb declares evidence in 1.0.0.

See Knowledge connection and Context resolver.

Conformance kit: conformance/knowledge/v1.

evidencestoreCopy Anchor Link

proto/numinance/ports/evidencestore/v1/evidencestore.proto. The write-once store of record for every Change's evidence chain, on storage the customer already owns.

• Callers: only the evidence context under the runner identity. Writes need the grant scope evidence.write and reads evidence.read; only a runner grant carries them, and a kernel floors rule denies them to every other actor kind. The scope names evidence.write, evidence.read and transparencylog.append are reserved.
• The store keeps opaque bytes. A record is its canonical form, keyed by change id and sequence. The provider never parses, canonicalizes or repairs records.

Conformance kit: conformance/evidencestore/v1.

See Record chain.

transparencylogCopy Anchor Link

proto/numinance/ports/transparencylog/v1/transparencylog.proto. An append-only Merkle log that anchors chain heads and attestations, served by a log that signs its own checkpoints: a customer-local ledger, Rekor (public or private) or a Tessera-based C2SP log. No provider re-signs another log's checkpoints.

• Callers: only the evidence context under the runner identity. Append needs the scope transparencylog.append and every read needs evidence.read.
• A leaf is exactly 33 bytes: kind 0x48 (chain head) or 0x41 (attestation), then a raw 32-byte hash. The verifier computes the leaf hash itself from the entry bytes the log returns.
• Lookup is gated by the capability transparencylog.lookup: a log without a search index does not serve it.

Conformance kit: conformance/transparencylog/v1.

See Anchoring and receipts.

ConformanceCopy Anchor Link

Every port has a conformance kit under conformance/PORT/v1 in the spec repository (authorexecutor, ciexecutor, evidencestore, knowledge, sandboxprovider, scm, ticketing, transparencylog, verifier), and an evidence kit for the evidence format. A kit is the executable definition of "implements the port". Run a provider against its kit before you trust it. See Conformance and, for the evidence vectors, Conformance vectors.

Failure modes and safeguardsCopy Anchor Link

TroubleshootingCopy Anchor Link

• A newer field is rejected by an older host: gate it on the negotiated spec version or on a capability.
• A verb you expected is missing from the plugin's allowed set: it has a non-empty capability, so it must be in the negotiated capabilities, not only the manifest.

Next stepsCopy Anchor Link