Release candidate: v0.2.0. These docs cover v0.2.0 scope and limits.

Veil v0.2.0

Release candidate documentation. v0.2.0 includes the capability introspection, runtime/governance hardening, and documentation refresh merged into develop. v0.1.3 remains the latest published package until v0.2.0 is published. See installation to build and install the candidate locally. This page describes the candidate scope; it is not a publication announcement.

Changes from v0.1.3

Release scope is based on main at 0b591f38b6146179cfea9d66f5bf50a1773520d7 and develop at e4df5be69105e8d2fcb76bd6b9c8e249beec3064. Contextual authorization and the public inbound MCP adapter already exist on main; they are not new v0.2.0 APIs.

• Capability introspection: public CapabilityDescriptor and exact describeCapability(name, version?); listCapabilities() now detaches schema records as well as descriptors. See the contract and limits below.
• Runtime hardening: observer failure containment, fail-closed authorization, own-property result references, unique step IDs, structural submission capture, and validation of every supplied capability version, including an empty string.
• Repository integrations: the generic HTTP capability endpoint now submits an ExecutionPlan through OperatorRuntime. The internal outbound MCP helper requires an explicit valid capability risk instead of assuming read access.
• Contributor tooling: an experimental local quality/governance comparison harness, its regression tests, and architecture decisions documenting the approved step-identity, structural-ownership, and introspection boundaries.
• Documentation: refreshed homepage and developer portal, shared navigation, public API examples, and detailed execution/trust-boundary documentation.

Compatibility and migration

• Give each step a unique ID within its plan. Repeated IDs now reject admission before job creation; IDs can still be reused in separate plans.
• Omit capabilityVersion to leave it unspecified, or provide the exact registered version. An empty string is supplied and must match; it is no longer ignored.
• Return an own decision: 'allow' or valid decision: 'deny' from authorizers. Inherited or malformed decisions fail closed; a denial reason, if present, must be a string.
• Result reference paths must address own properties. Prototype properties can no longer satisfy a result reference.
• Mutating introspection descriptors or their declared schema fields no longer changes registered metadata or validation. Descriptors remain mutable snapshots.
• Repository HTTP clients cannot authorize work with approved: true; the host must configure an authorizer. Unknown capabilities return 404, admission validation failures 400, explicit denial 403, and failed jobs otherwise 500.
• Repository contributors using the internal createMcpCapability helper must supply its explicit risk argument. This helper and HTTP routes are not public package exports.

The package root remains the supported consumer entry point. No internal registry, provider implementation, store, or validator is newly exported. The package version is 0.2.0; ExecutionPlan format remains version: '1.0'.

Reasoning proposes; Veil governs execution

Software, humans, and planners produce a declarative ExecutionPlan. OperatorRuntime validates the plan, resolves registered capabilities and earlier results, validates resolved inputs, authorizes each step, and records execution outcomes. Capabilities define work; providers interact with infrastructure. No particular model or reasoning system is required.

Governed-execution hardening

• Observer failures: internal event-subscriber throws and rejections do not change execution outcomes or stop delivery to other subscribers. Publication still awaits subscribers; there is no observer timeout or mutation isolation.
• Explicit authorization: execution requires a valid own decision: 'allow' on a non-null, non-array object. Malformed decisions and authorizer failures fail closed. The default policy still allows reads and denies writes/destructive work.
• Result references: each result-path segment must be an own property. Inherited properties are rejected; own getters and proxy traps can still run.
• Step identity: duplicate step IDs reject admission before a job is created. Equality is exact within a plan; separate plans may reuse IDs.
• Structural ownership: executePlan captures a runtime-owned structural envelope before admission. Validation and job materialization use that same structure, including step order, identity, capability bindings and input root bindings. Later caller structural edits cannot redirect that submission.

These boundaries do not make inputs deeply immutable. Nested input and reference contents remain shared. Authorization and invocation share resolved input, with no revalidation between them; deep value stability from authorization to capability invocation is not guaranteed. Structural capture does not cover stored-job replay. See trust boundaries.

Deterministic capability introspection

runtime.listCapabilities() returns inventory in registration order. runtime.describeCapability(name, version?) performs exact, case-sensitive lookup; a supplied version must match exactly. An unknown name or version mismatch returns undefined. This is registered-name lookup, not semantic discovery.

The public CapabilityDescriptor contains name, version, description, risk and inputSchema. Returned descriptors, schema records and field records are fresh, detached and mutable, not frozen. The schema describes Veil’s limited field contract, not full JSON Schema. Inventory is process-global, not private to a runtime or filtered for a caller. Duplicate names remain rejected even when versions differ.

Three questions stay separate:

1. Introspection: What execution capabilities are registered?
2. External application or reasoning: Which capability is relevant?
3. Authorization: May this caller execute it with this input?

Introspection invokes no authorizer, capability or provider. Registration implies neither permission nor provider readiness. Veil adds no semantic search, ranking, embeddings or LLM-driven capability selection. Execution still passes through a normal ExecutionPlan and runtime governance.

See the OperatorRuntime reference for the API example and capability API for the descriptor contract. These examples require the v0.2.0 candidate; do not use them with the published v0.1.3 package.

What remains application-owned

Relevance selection, human approval UI, provider credentials, and external side effects remain application responsibilities. Governed execution is not a sandbox or a promise of deterministic external results. Plans remain sequential; this work adds no DAGs, parallel execution, retries, cancellation, rollback or idempotency enforcement.

Governance tooling limits

The quality harness complements the functional/package checks; it does not prove complete authorization coverage. Its existing legacy exceptions are direct capability dispatch in GET /api/linkedin/status and direct internal job execution in POST /api/jobs/:id/execute. The latter performs per-step authorization but bypasses OperatorRuntime and plan admission. Those paths are not included in the public npm package. Their migration is deferred; v0.2.0 must not be described as eliminating every repository execution bypass. The maintainer accepted the reviewed governance baseline and verification-control findings for this release. That acceptance does not resolve these exceptions, expand checker coverage, or turn the fixed-base comparison against 0b591f3 into a pass.