Skip to content
AIGP

RFC-012: Artifact Lifecycle Protocol (ALP) — 5. Protocol Messages

AIGP Specification › RFC-012: Artifact Lifecycle Protocol (ALP) › 5. Protocol Messages

← 4. Lifecycle States · Section index · 6. Provenance Chain →

5. Protocol Messages

5.1 CREATE

Sent by an agent to register a new artifact in DRAFT state.

POST /alp/v1/artifacts
Headers:
  X-ALP-Signature: hmac-sha256={signature}
  X-ALP-Timestamp: {iso_timestamp}
  X-ALP-App-Id: {app_id}
  X-ALP-Agent-Id: {agent_id}
  Content-Type: application/json


Body:
{
  "protocol_version": "1",
  "message_type": "CREATE",
  "artifact_type": "PYTHON_SCRIPT",
  "name": "remediate-prisma-gaps.py",
  "producer": {
    "agent_id": "agent-remediation-v1",
    "app_id": "runbook-service",
    "aigp_request_id": "req-1714800000000",
    "acp_context_id": "ctx-1714800000000"
  },
  "content_base64": "aW1wb3J0IGJvdG8zCi4uLg==",
  "compensation_content_base64": "aW1wb3J0IGJvdG8zCiMgcm9sbGJhY2suLi4=",
  "blast_radius": {
    "scope": "ACCOUNT",
    "affected_resources": ["iam:policy", "iam:role"],
    "estimated_count": 12
  }
}

Response:

{
  "artifact_id": "art-20260504-001",
  "state": "DRAFT",
  "content_hash": "sha256:a1b2c3d4e5f6...",
  "compensation_artifact_id": "art-20260504-001-rollback",
  "created_at": "2026-05-04T10:00:00Z"
}

Validation rules:

  • If artifact_type is executable (see 3), compensation_content_base64 MUST be provided.
  • aigp_request_id MUST reference a valid, ALLOW’d AIGP request.
  • acp_context_id MUST reference a valid ACP context assembly.

5.2 PROMOTE

Sent to transition an artifact between lifecycle states.

POST /alp/v1/artifacts/{artifact_id}/promote
Headers:
  X-ALP-Signature: hmac-sha256={signature}
  X-ALP-Timestamp: {iso_timestamp}
  X-ALP-App-Id: {app_id}
  X-ALP-Actor-Id: {actor_id}
  Content-Type: application/json


Body:
{
  "protocol_version": "1",
  "message_type": "PROMOTE",
  "artifact_id": "art-20260504-001",
  "from_state": "DRAFT",
  "to_state": "REVIEW",
  "reason": "Remediation script ready for review",
  "actor": {
    "actor_id": "agent-remediation-v1",
    "actor_type": "AGENT"
  }
}

Response:

{
  "artifact_id": "art-20260504-001",
  "previous_state": "DRAFT",
  "current_state": "REVIEW",
  "transition_hash": "sha256:b2c3d4e5f6g7...",
  "timestamp": "2026-05-04T10:05:00Z"
}

For REVIEW APPROVED promotion:

{
  "protocol_version": "1",
  "message_type": "PROMOTE",
  "artifact_id": "art-20260504-001",
  "from_state": "REVIEW",
  "to_state": "APPROVED",
  "reason": "Script reviewed, blast radius acceptable",
  "actor": {
    "actor_id": "owner@ai-governance-protocol.org",
    "actor_type": "HUMAN"
  },
  "approval": {
    "reviewed_hash": "sha256:a1b2c3d4e5f6...",
    "conditions": [],
    "expiry": "2026-05-04T22:00:00Z"
  }
}

The reviewed_hash MUST match the artifact’s current content_hash. If the content was modified after the reviewer inspected it, the promotion MUST be rejected.

5.3 EXECUTE

Sent by the runbook-service orchestrator to execute an approved artifact.

POST /alp/v1/artifacts/{artifact_id}/execute
Headers:
  X-ALP-Signature: hmac-sha256={signature}
  X-ALP-Timestamp: {iso_timestamp}
  X-ALP-App-Id: runbook-service
  Content-Type: application/json


Body:
{
  "protocol_version": "1",
  "message_type": "EXECUTE",
  "artifact_id": "art-20260504-001",
  "execution_context": {
    "run_id": "run-20260504-001",
    "environment": "dev",
    "parameters": {
      "target_account": "705909755305",
      "dry_run": false
    }
  },
  "approved_hash": "sha256:a1b2c3d4e5f6..."
}

Response (on completion):

{
  "artifact_id": "art-20260504-001",
  "state": "COMPLETED",
  "execution": {
    "run_id": "run-20260504-001",
    "started_at": "2026-05-04T11:00:00Z",
    "completed_at": "2026-05-04T11:02:30Z",
    "duration_ms": 150000,
    "exit_code": 0,
    "output_summary": "12 policies remediated successfully",
    "output_ref": {
      "s3_key": "executions/run-20260504-001/output.json"
    }
  }
}

Response (on failure):

{
  "artifact_id": "art-20260504-001",
  "state": "FAILED",
  "execution": {
    "run_id": "run-20260504-001",
    "started_at": "2026-05-04T11:00:00Z",
    "failed_at": "2026-05-04T11:01:15Z",
    "duration_ms": 75000,
    "exit_code": 1,
    "error": "IAM policy limit exceeded for account 705909755305",
    "output_ref": {
      "s3_key": "executions/run-20260504-001/output.json"
    },
    "compensation_triggered": true,
    "compensation_artifact_id": "art-20260504-001-rollback"
  }
}

Validation rules:

  • approved_hash MUST match the artifact’s current content_hash. If the content was modified after approval, execution MUST be rejected.
  • The artifact MUST be in APPROVED state.
  • The approval MUST NOT be expired (see approval.expiry in 5.2).

5.4 ARCHIVE

Sent to move a completed or failed artifact to terminal archive state.

POST /alp/v1/artifacts/{artifact_id}/archive
Headers:
  X-ALP-Signature: hmac-sha256={signature}
  X-ALP-Timestamp: {iso_timestamp}
  X-ALP-App-Id: {app_id}
  Content-Type: application/json


Body:
{
  "protocol_version": "1",
  "message_type": "ARCHIVE",
  "artifact_id": "art-20260504-001",
  "retention_days": 365,
  "archive_reason": "Execution completed successfully"
}

Response:

{
  "artifact_id": "art-20260504-001",
  "state": "ARCHIVED",
  "archived_at": "2026-05-04T12:00:00Z",
  "retention_until": "2027-05-04T12:00:00Z",
  "final_hash": "sha256:c3d4e5f6g7h8...",
  "provenance_ref": "provenance/art-20260504-001.json"
}

Archived artifacts MUST NOT be modified. The final_hash covers the complete artifact record including all transition signatures.

← 4. Lifecycle States · Section index · 6. Provenance Chain →