# Runtime Integration Contract

## 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 version, tag, or range |
| `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:

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

Key response fields:

```json
{
  "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.

## Possible Future API

If a clear consumer appears, such as Runtime needing only the compliance snapshot without full skill details, SkillHub can add an immutable version-level endpoint:

```text
GET /api/skill-versions/{skillVersionId}/compliance
```

For now, reuse the version detail response to avoid designing multiple APIs before the caller contract is stable.
