Runtime Integration: Version Resolution, Downloads, and Compliance Snapshots

Responsibility Boundary

SkillHub and Agent Runtime own different facts:

System	Source of truth
SkillHub	Skill packages, versions, metadata, compliance declaration snapshots, downloads, and review records
Agent Runtime	Actual skill execution, inputs and outputs, model calls, tool calls, and execution traces

SkillHub does not execute skills, so it does not record Runtime traces and does not decide whether a real execution was compliant. SkillHub provides version-level facts: what compliance declarations were included in an immutable skill version at publish time, and the stable digest of that normalized snapshot.

What Runtime Should Record

When Runtime needs to connect an execution trace with SkillHub compliance declarations, record these fields:

Field	Source	Description
registryUrl	Runtime configuration	SkillHub registry URL
namespace	SkillHub coordinate	Skill namespace, such as global or a team slug
skillSlug	SkillHub coordinate	Skill slug
requestedVersion	Runtime request	User-requested exact version or tag
resolvedVersion	SkillHub response	Exact resolved version
skillVersionId	Version id from SkillHub response	Immutable version ID and the primary audit join key
complianceSnapshotDigest	complianceSnapshot.digest	Stable digest of the version-level compliance declaration snapshot
packageDigest	Download or install flow	Skill package content digest, useful for confirming executed content
runtimeTraceId	Runtime	Execution trace ID generated by Runtime

If Runtime uses an Astron-specific trace schema, it may map these fields into x-astron-* keys. That is a Runtime-owned trace convention; SkillHub server does not need to write or parse those trace fields.

Reading Version-Level Compliance Snapshots

The first phase does not expose a standalone compliance API. Runtime can read the version ID and snapshot from the existing version detail endpoint:

GET /api/v1/skills/{namespace}/{slug}/versions/{version}

The example below shows fields inside the successful response’s data, not the full HTTP response. Check the outer business code before reading data.id and data.complianceSnapshot. Versions without declarations may have no snapshot; absence does not establish certification or an execution violation.

{
  "id": 123,
  "version": "1.2.0",
  "complianceSnapshot": {
    "schemaVersion": "1.0",
    "digest": "sha256:8d8c...",
    "items": [
      {
        "standard": "mitre-attack",
        "version": "v19.1",
        "controlId": "T1059",
        "title": "Command and Scripting Interpreter",
        "evidence": [
          {
            "type": "packaged-file",
            "path": "references/mitre-t1059.md",
            "sha256": "sha256:..."
          }
        ]
      }
    ]
  }
}

Runtime should write both id and complianceSnapshot.digest to the execution trace. Recording only the digest is not enough, because the version ID is needed to locate the full snapshot across registries or future migrations.

Recommended Execution Flow

1. Runtime resolves the requested skill coordinate and version.
2. Runtime reads exact version details from SkillHub.
3. Runtime downloads and verifies the skill package.
4. Runtime executes the skill.
5. Runtime records these facts in its own trace:
   • SkillHub registry;
   • skill coordinate;
   • exact version;
   • skillVersionId;
   • complianceSnapshotDigest;
   • Runtime-owned execution evidence.

An audit system can then start from the Runtime trace, locate the exact execution, and query SkillHub for the compliance declaration snapshot that existed when that version was published.

Anti-Patterns

• Do not copy the raw x-astron-compliance declaration into a trace and let Runtime mutate it.
• Do not record only the skill slug without the version ID; the slug identifies the skill container, not an immutable version.
• Do not treat SkillHub compliance declarations as third-party certification.
• Do not require SkillHub to record model inputs and outputs; that belongs to the Runtime audit boundary.

Resolve, inspect, then download

Choose the registry, skill coordinate and caller identity first. These are HTTP request examples, not shell commands; replace the example coordinate with a real resource.

GET /api/v1/skills/global/example-skill/resolve?version=1.2.0
GET /api/v1/skills/global/example-skill/versions/1.2.0
GET /api/v1/skills/global/example-skill/versions/1.2.0/download

version is exact; use tag for a tag, and do not supply both. This endpoint does not resolve ranges such as ^1.2.0. Resolution returns skillId, namespace, slug, version, versionId, fingerprint, matched, and downloadUrl. Use that exact version for subsequent requests rather than resolving latest again before execution.

Version details use the common response envelope. This illustrative example omits some detail fields:

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 123,
    "version": "1.2.0",
    "status": "PUBLISHED",
    "fileCount": 2,
    "totalSize": 2048,
    "complianceSnapshot": null
  },
  "timestamp": "2026-01-01T00:00:00Z",
  "requestId": "example-request-id"
}

A null snapshot can mean no declaration or historical metadata that cannot be projected. Do not invent a digest. The registry package fingerprint and compliance snapshot digest identify different content. If you hash the downloaded ZIP yourself, record its algorithm and object separately; do not assume it equals the registry fingerprint.

Downloads return either ZIP bytes or a 302 with an object-storage Location. Do not forward registry credentials to the storage host when following a redirect. The CLI provides an existing installation and validation flow. A temporary download URL is not a durable resource identifier.

Permissions and failure handling

• Anonymous callers can read visible public published resources. Restricted resources still require the appropriate identity, namespace membership or ownership; an anonymously accessible route does not make every resource public.
• Version details support authorized maintainer previews. Readability does not imply installability: resolution requires an installable version. Record and check status; do not treat pending preview content as a published release.
• Stop on missing, inaccessible or unavailable versions. Do not silently substitute another skill, registry or latest version.
• Retain request IDs and redacted errors for investigation, not tokens, signed URLs or secrets from runtime inputs.

Verify at least public resolution and download, anonymous rejection of restricted resources, explicit failure for unavailable versions, null snapshots, and credential-safe redirects. Execution traces remain in the runtime's own system; these endpoints do not accept execution results.