Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 28 additions & 16 deletions packages/tasks-capability/README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,19 @@
# Affected Verification capability for Opsle Tasks

`@opsle/affected-verification-tasks-capability` **0.1.0** is an independently
`@opsle/affected-verification-tasks-capability` **0.2.0** is an independently
versioned, dependency-free capability owned and released by the public Affected
Verification repository. AV remains the verification planning authority. Tasks
owns operator grants, command execution, observed results, repair, and release.
The package neither runs catalog commands nor authorizes deployment.
The package neither runs catalog commands nor authorizes deployment. AV remains
`OBSERVE_SHADOW`: its proposal is not execution authority, and full verification
must remain authoritative.

The executable ESM entry point implements the generic
`opsle.capability-manifest.v1` / `opsle.capability-result.v1` contract. Both
`verification.plan` and `verification.capture` are **required deterministic
authorities**. `default_enabled` is **false**. No AV identity branches, new central
`verification.plan`, `verification.shadow`, and `verification.capture` are
**required deterministic authorities**. The shadow hook validates the complete
authoritative result, uses AV's native classifier, and returns a bound receipt.
`default_enabled` is **false**. No AV identity branches, new central
Tasks dependencies, private Tasks imports, sibling checkouts, Graphify dependency,
or structural-evidence contract are needed.

Expand All @@ -19,7 +23,7 @@ Build from an AV checkout with Node 20+ and npm:

```sh
npm run pack:tasks-capability
sha256sum opsle-affected-verification-tasks-capability-0.1.0.tgz
sha256sum opsle-affected-verification-tasks-capability-0.2.0.tgz
```

`npm pack` builds the adapter, includes the current AV core, runtime helpers,
Expand All @@ -29,13 +33,13 @@ network dependencies are required. Review the artifact hash and provenance
before an operator installs it outside repositories and agent-writable paths:

```sh
npm install --prefix /srv/opsle-capabilities/av-0.1.0 \
npm install --prefix /srv/opsle-capabilities/av-0.2.0 \
--ignore-scripts --no-audit --no-fund \
./opsle-affected-verification-tasks-capability-0.1.0.tgz
./opsle-affected-verification-tasks-capability-0.2.0.tgz
```

Set the operator-owned `OPSLE_CAPABILITY_PATH` to the installed directory:
`/srv/opsle-capabilities/av-0.1.0/node_modules/@opsle/affected-verification-tasks-capability`.
`/srv/opsle-capabilities/av-0.2.0/node_modules/@opsle/affected-verification-tasks-capability`.
Tasks also accepts the generic `capabilityRoots` configuration. Multiple roots
use the platform path delimiter. Include the individually installed roots for
other required authorities and observers. **Replace** the bundled AV discovery
Expand All @@ -58,9 +62,9 @@ An absent required authority blocks verification, including after a revoke.
## Compatibility and schemas

The real generic runtime compatibility target is Opsle Tasks revision
`e1207c5264c59e14efe9838bba3a33ba504665d2` (Node 24+ for its complete regression
`b76d6253b405469b79d30b260f7ad09827052a4a` (Node 24+ for its complete regression
suite). Its `src/capabilities.js` SHA-256 is
`d8568872a1d76e5ac78e134154683b43c7ed46c2b583eaef0e9aac3569a09f30`.
`62dca002d729c82ca00a66fdb6edcbac692eca770ca6f771dea0c7e68ffd3408`.
Tests import that unmodified runtime only as a compatibility test dependency;
the installed capability never imports Tasks source. Execution metadata comes
from generic `services.executionConfig`; project/task/attempt/execution bindings
Expand All @@ -70,6 +74,7 @@ operator-owned.
| Hook | Request | Response |
| --- | --- | --- |
| `verification.plan` | `opsle.execution.verification-request.v1` | `opsle.execution.verification-analysis.v1` |
| `verification.shadow` | `opsle.execution.verification-shadow-request.v1` | `opsle.execution.verification-shadow-result.v1` |
| `verification.capture` | `opsle.execution.change-capture-request.v1` | `opsle.execution.change-set.v1` |

All JSON Schemas are in `schemas/`. They include the immutable task manifest,
Expand All @@ -82,7 +87,10 @@ Structural validation supplements AV's native cross-field semantic validation;
it cannot establish completeness or provenance by itself.

The compatibility analysis envelope retains `change`, `decision`, `error`,
`evidencePath`, `inputPath`, `receiptPath`, and `record`. An `ok` capability envelope
`evidencePath`, `inputPath`, `receiptPath`, and `record`. Planning does not create
a value receipt: one exists only after exact full-catalog results are validated
and shadow-classified. The shadow response returns it through the ordinary
`receipts` array and retains the matching private sidecar. An `ok` capability envelope
means analysis completed, **not that verification passed**. A failed analysis has
`decision: null`, an explicit error, and `ANALYSIS_FAILED` evidence. The Tasks
consumer must use full configured verification or stop. Missing manifests use
Expand All @@ -97,9 +105,12 @@ and staged Git tree identities. The manifest is read from the immutable base,
not agent-modified content. Every action must match the exact immutable catalog
partition and command. The adapter validates canonical decision identity and
recomputes the AV decision to check provenance/completeness. Unknown, incomplete,
or opaque evidence cannot justify an unexplained skip. Tasks must compare the
post-verification capture tree with the planned tree before accepting changes;
the package never decides that command execution passed.
or opaque evidence cannot justify an unexplained skip. Tasks must execute the
full catalog, pass its exact results to the shadow hook, and compare the
post-verification capture tree with the planned tree before accepting changes.
Unknown trust state, stale execution identity, source drift, incomplete results,
and invalid receipts fail closed; the package never decides that command
execution passed.

SSH target validation, argv quoting, strict host-key checking, connection and
remote process deadlines, bounded Git output, and private evidence are retained
Expand All @@ -111,7 +122,8 @@ all packaged files that affect planning. Operator-protected installation roots
remain the trust boundary; hashes do not make writable installations trustworthy.

OBSERVE/SHADOW observations and historical benchmarks retain their existing
limits. No observation is promoted to execution authority or production trust.
limits. Proposed skips are proposals, not savings or avoided executions. No
observation is promoted to execution authority or production trust.
External structural evidence is not accepted by this interface and cannot narrow
verification; only AV's own provenance and completeness decision can justify
selection. The core remains separately usable without Tasks.
Expand Down Expand Up @@ -151,7 +163,7 @@ recorded revision, then run:
npm run verify
OPSLE_TASKS_RUNTIME_ROOT=/path/to/pinned/opsle-tasks npm run verify:tasks-capability
npm run pack:tasks-capability
sha256sum opsle-affected-verification-tasks-capability-0.1.0.tgz
sha256sum opsle-affected-verification-tasks-capability-0.2.0.tgz
```

The second command is mandatory for release: it refuses to skip if Tasks is
Expand Down
10 changes: 9 additions & 1 deletion packages/tasks-capability/opsle-capability.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"schema": "opsle.capability-manifest.v1",
"id": "opsle.affected-verification",
"name": "Affected Verification",
"version": "0.1.0",
"version": "0.2.0",
"adapter": "adapter.js",
"default_enabled": false,
"configuration_schema": "opsle.affected-verification.tasks-config.v2",
Expand All @@ -23,6 +23,14 @@
"role": "authority",
"execution": "deterministic",
"failure": "required"
},
{
"name": "verification.shadow",
"input_schema": "opsle.execution.verification-shadow-request.v1",
"output_schema": "opsle.execution.verification-shadow-result.v1",
"role": "authority",
"execution": "deterministic",
"failure": "required"
}
]
}
2 changes: 1 addition & 1 deletion packages/tasks-capability/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@opsle/affected-verification-tasks-capability",
"version": "0.1.0",
"version": "0.2.0",
"description": "Independent Affected Verification authority for the generic Opsle Tasks capability contract",
"type": "module",
"license": "Apache-2.0",
Expand Down
79 changes: 71 additions & 8 deletions packages/tasks-capability/schemas/evidence-v1.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@
"analysis_error",
"verification_results",
"fallback",
"trust_stage",
"shadow",
"limitations"
],
"properties": {
Expand Down Expand Up @@ -71,7 +73,7 @@
}
}
},
"status": {
"status": {
"enum": [
"ANALYSIS_FAILED",
"ANALYZED",
Expand All @@ -81,7 +83,13 @@
"VERIFICATION_RUNNING",
"VERIFICATION_FAILED",
"NO_AUTOMATED_VERIFICATION",
"VERIFICATION_PENDING"
"VERIFICATION_PENDING",
"SHADOW_HEALTHY",
"FULL_VERIFICATION_REQUIRED",
"SHADOW_BROADENED",
"SHADOW_MISS_REVIEW_REQUIRED",
"SHADOW_INDETERMINATE",
"AV_INVALID_DEGRADED"
]
},
"mechanism": {
Expand Down Expand Up @@ -292,6 +300,14 @@
"FAILED"
]
},
"command_outcome": {
"enum": [
"PASSED",
"FAILED",
"SIGNALED",
"INTERRUPTED"
]
},
"exit_code": {
"anyOf": [
{
Expand All @@ -302,7 +318,7 @@
}
]
},
"signal": {
"signal": {
"anyOf": [
{
"type": "string",
Expand All @@ -311,8 +327,22 @@
{
"type": "null"
}
]
},
]
},
"interrupted": {
"type": "boolean"
},
"interruption_reason": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
]
},
"duration_ms": {
"anyOf": [
{
Expand Down Expand Up @@ -346,7 +376,7 @@
}
]
},
"evidence_path": {
"evidence_path": {
"anyOf": [
{
"type": "string",
Expand All @@ -355,8 +385,29 @@
{
"type": "null"
}
]
}
]
},
"evidence_status": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
]
},
"evidence_limitation": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
}
}
}
},
Expand Down Expand Up @@ -396,6 +447,18 @@
}
]
},
"trust_stage": {
"anyOf": [
{ "enum": ["OBSERVE_SHADOW", "UNKNOWN"] },
{ "type": "null" }
]
},
"shadow": {
"anyOf": [
{ "type": "object" },
{ "type": "null" }
]
},
"limitations": {
"type": "array",
"items": {
Expand Down
Loading
Loading